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Preface 



Manual Objectives 

The RSX-HM-PLUS and Micro /RSX System Library Routines Reference Manual describes the use 
and function of the system library routines that may be called from MACRO-11 assembly 
language programs. 

Intended Audience 

This manual is intended for use by experienced MACRO-11 assembly language programmers, 
RSX-HM-PLUS and Micro/RSX system managers, and applications programmers. 

Structure of This Document 

Chapter 1 presents a general description of the services provided by the system library routines 
and their functional relationships. 

Chapter 2 describes the use and function of the register handling routines. 

Chapter 3 describes the use and function of the arithmetic routines. 

Chapter 4 describes the use and function of the input data conversion routines. 

Chapter 5 describes the use and function of the output data conversion routines. 

Chapter 6 describes the use and function of the output formatting routines. 

Chapter 7 describes the use and function of the dynamic memory management routines. 

Chapter 8 describes the use and function of the virtual memory management routines. 

Chapter 9 summarizes the calling sequences of the system library routines. 

Appendix A describes a routine that allows a program to access modules in a universal library 
as if they were files. 



vn 



Associated Documents 

The following manuals are prerequisite sources of information for readers of this manual: 

• The PDP-11 MACRO-U Language Reference Manual 

• The RSX-11M-PLUS and Micro/RSX Task Builder Manual 

• The manuals referred to in Appendix A 

Readers should also refer to the RSX-11M-PLUS Information Directory and Master Index and the 
Micro/RSX Master Index for descriptions of other documents associated with this manual. 
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Chapter 1 
Introduction 



The routines described in this manual were written to provide commonly needed capabilities 
for DIGITAL-supplied utilities. We supply documentation for them because the routines are 
general enough to be used regularly by most MACRO-11 programmers. Note, however, that 
the basic functionality of the routines described in this manual cannot be changed because of 
the potentially widespread effect it may have on our system utilities. 

The system library routines may be called by MACRO-11 assembly language programs to 
perform the following services: 

• Save and restore register contents to enable transfers of control between the calling program 
and called subroutines 

• Perform integer and double-precision multiplication and division 

• Convert ASCII input data to internal binary and Radix-50 format 

• Convert internal binary and Radix-50 data to ASCII output data 

• Convert and format output data to produce text for a readable printout or display 

• Manage the dynamic memory space available to the task that requires a small-to-moderate 
amount of resident memory for data 

• Manage memory and disk file storage to accommodate tasks that require large amounts of 
memory for data that must be transferred between memory and a disk work file 

This manual describes the procedures for calling the library routines from within the source 
program, the output that is returned to the executing task, and the interaction between the 
library routines and the executing task. 

The system library routines interface with each other to perform their various services. For 
example, the data conversion routines call the arithmetic routines to perform the required 
multiplication and division. All library routines preserve the contents of the calling task's 
registers, generally by calling the appropriate register handling routine to do the following: 

• Save register contents on the stack 

• Subsequently restore the contents of the registers 
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• Return control to the calling task 

The data conversion and format control functions performed by the Edit Message Routine 
require calls to the output data conversion routines, which in turn call other routines. 

The virtual memory management routines function as an automatic control system to allocate 
and deallocate memory, maintain page addresses and status, and swap pages between memory 
and disk storage to accommodate large amounts of data in a limited amount of physical 
(dynamic) memory. 

The system library routines communicate with the calling task by means of registers in which 
output is returned or by settings of the C bit in the Condition Code of the Processor Status 
Word. The calling task can usually determine whether a requested service was successfully 
performed by examining the output register or registers or by testing the C bit setting when 
control is returned from the library routine. Exceptions to this procedure are described in the 
detailed discussions of given routines. 

The system library routines are supplied to users as object code in the following files: 

• The system library file (SYSUB.OLB), which contains the following routines: 

— the register handling routines (described in Chapter 2) 

— the arithmetic routines (described in Chapter 3) 

— the input and output data conversion routines (described in Chapter 4 and Chapter 5) 

— the output formatting routines (described in Chapter 6) 

— the dynamic memory allocation and release routines (described in Chapter 7) 

— the universal library access routines (described in Appendix A) 

• The memory management routines file (VMLIB.OLB), which contains the dynamic and 
virtual memory management routines 

At task-build time, the Task Builder will automatically search the system library file for any 
referenced routines. However, the VMLIB.OLB file must be specified at task-build time if a task 
has referenced the dynamic memory initialization routine (described in Chapter 7) or any of the 
virtual memory management routines (described in Chapter 8 of this manual). 

A summary of each procedure for using the system library routines is given in Chapter 9. This 
is quick-reference material provided for the MACRO-11 assembly language programmer who 
has become familiar with the detailed procedures that are explained in Chapters 2 through 8 of 
this manual. 

Additional Executive and I/O routines available to RSX-11 systems users are described in other 
manuals. See the RSX-11M-PLUS Information Directory and Master Index for more information. 

If the task that includes system library routines also references a position-independent resident 
library, it is possible that program section names may conflict. Routines included in a task 
cannot reside in the same program section as routines referenced in the position-independent 
resident library. Table 1-1 lists the program section names and the system library routines that 
reside in each program section. If your task includes a routine that uses a program section 
listed in Table 1-1 and the task also references a position-independent resident library routine 
that uses the same program section, the Task Builder generates a fatal error. To determine how 
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to include the code in your task and avoid a conflict of program section names, refer to the 
RSX-UM-PLUS and Micro /RSX Task Builder Manual. 

Table 1-1: Program Section Names for SYSLIB Routines 



Program Section 
Name 



SYSLIB Routines 

Module Routine 

Name Name(s) 



.BLK. 



PUR$D 
PUR$I 
$$RESL 
$$RESM 



CATB 


$CDTB 




$COTB 


CAT5 


$CAT5 


CBTA 


$CBDAT 




$CBDMG 




$CBDSG 




$CBOMG 




$CBOSG 




$CBTA 




$CBTMG 


CDDMG 


$CDDMG 


CVTUC 


$CVTUC 


C5TA 


$C5TA 


EDDAT 


$DAT 




$TIM 


OD2CT 


.DD2CT 




.OD2CT 


SAVAL 


$SAVAL 


SAWR 


$SAWR 


CAT5B (data) 


$CAT5B 


EDTMG (data) 


$EDTMG 


CAT5B (instruction) 


$CAT5B 


EDTMG (instruction) 


$EDTMG 


SAVRG 


$SAVRG 


SAVR1 


.SAVR1 


ARITH 


$Drv 




$MUL 


DARITH 


$DDIV 




$DMUL 
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Chapter 2 

Register Handling Routines 



The system library contains the following register handling routines: 

• Save All Registers Routine ($SAVAL), which saves and subsequently restores Registers 
through 5 

• Save Registers 3-5 Routine ($SAVRG), which saves and subsequently restores Registers 3 
through 5 

• Save Registers 0-2 Routine ($SAWR), which saves and subsequently restores Registers 
through 2 

• Save Registers 1-5 Routine (.SAVR1), which saves and subsequently restores Registers 1 
through 5 

The register handling routines function as coroutines to enable control swapping between 
themselves, a subroutine, and the original caller of the subroutine. The register handling 
routines are also called by other routines in the system library, as noted throughout this 
manual. 

To illustrate the effect of using the register handling routines, assume the following situation: 

An original caller calls a subroutine. The subroutine calls a register handling coroutine. The 
coroutine preserves (pushes onto the stack) the contents of the specified registers and issues 
a coroutine call back to the subroutine. The subroutine executes to completion, then a return 
instruction is executed to swap control back to the coroutine. The coroutine restores (pops from 
the stack) the initial contents of the registers and returns to the original caller. 

Figure 2-1 illustrates the control swapping function performed by the register handling routines. 



Register Handling Routines 2-1 



Figure 2-1: Control Swapping of the Register Handling Routines 



ORIGINAL CALLER 
START 



Legend 

CALL (subroutine) = JSR PC, subroutine 
RETURN -RTSPC 



CALL (Subroutine) ' 



"(Subroutine) 

JSR r.$SAVxx 



-«»• SSAVxx (save registers) 



i (issue coroutine call 
; to subroutine) 



RETURN- 



END 



(restore registers) 



RETURN (to original caller) 
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2.1 Save All Registers Routine ($SAVAL) 

The $SAVAL routine saves and subsequently restores Registers through 5 for a subroutine. 
The $SAVAL routine functions as a coroutine that swaps control between itself, a subroutine, 
and the original caller. 

Format 

To call the $SAVAL routine, include the following entries in your source program: 

1. Enable the $SAVAL routine to return control to the original caller by including the following 
instruction in the calling routine: 

CALL subroutine 

2. Call the $SAVAL routine by including the following instruction in the subroutine: 

CALL $SAVAL 
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3. Enable the subroutine to return control to the $SAVAL routine by including the following 
return instruction in the subroutine: 

RTS PC 

Description 

Figure 2-1 illustrates the control swapping function performed by the register handling routines. 

Upon entry to the $SAVAL routine, the program stack contains the return address to the original 
caller and the return address of the subroutine. The $SAVAL routine pushes the contents of 
Registers through 4 onto the stack. 

The $SAVAL routine moves the subroutine's return address to the position following Register 
O's contents and moves the current contents of Register 5 to the stack above the contents of 
Register 4. 

The $SAVAL routine issues a coroutine call, in the form CALL @(SP)+, to swap control back 
to the subroutine. The coroutine call replaces the subroutine's return address with the return 
address to the $SAVAL routine. When control returns to the subroutine, the stack pointer points 
to $SAVAL's return address. The stack contains the following information: 

Return address to $SAVAL 

Contents of Register 

Contents of Register 1 

Contents of Register 2 

Contents of Register 3 

Contents of Register 4 

Contents of Register 5 

Return address to original caller 

The subroutine executes until a return instruction (RTS PC) is executed, which swaps control 
back to the $SAVAL routine. The contents of Registers through 5 are restored (popped from 
the stack) and the $SAVAL routine returns, by means of the RTS PC instruction, to the original 
caller. 

Example 

The following source statements illustrate the use of the $SAVAL routine: 

• A calling routine contains the following instruction: 

CALL FNDSEC 

• The subroutine FNDSEC contains the following code: 
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FNDSEC: CALL 


$SAVAL 


MOV 


$RTSEG,R1 


CALL 


$CVRL 


ADD 


#S$GCST,RO 


MOV 


RO.-(SP) 


MOV 


$CRELM,R1 


ADD 


#S$YM.R1 


CALL 


$SRCH 


BCS 


10$ 


MOV 


Rl.CRVSC 


TST 


(SP) + 


RTS 


PC 



10$: 



SAVE THE VOLATILE REGISTERS 

GET THE ROOT SEGMENT DESCRIPTOR VIRTUAL ADDRESS 

CONVERT TO DYNAMIC MEMORY ADDRESS 

POINT TO THE .PSECT TABLE ENTRIES 

SAVE TABLE ENTRIES 

GET THE CURRENT ELEMENT DESCRIPTOR ADDRESS 

ADJUST POINTER TO SYMBOL ENTRY 

AND LOOK FOR THE SYMBOL. . . 

IF C-SET, NO SECTION ENTRY 

IF C-CLR. YES. RESET CURRENT VIRTUAL SECTION 

ADDRESS 

CLEAN OFF STACK 

AND RETURN SUCCESSFULLY 

SUBROUTINE CONTINUES 



2.2 Save Registers 3-5 Routine ($SAVRG) 

The $SAVRG routine saves and subsequently restores Registers 3 through 5 for a subroutine. 
The $SAVRG routine functions as a coroutine that swaps control between itself, a subroutine, 
and the original caller. 

Format 

To call the $SAVRG routine, include the following entries in your source program: 

1. Enable the $SAVRG routine to return control to the original caller by including the following 
Jump to Subroutine instruction in the calling routine: 

CALL subroutine 

2. Call the $SAVRG routine by including the following Jump to Subroutine instruction in the 
subroutine: 

JSR R5,$SAVRG 

3. Enable the subroutine to return control to the $SAVRG routine by including the following 
return instruction in the subroutine: 

RTS PC 

Description 

Figure 2-1 illustrates the control swapping function performed by the register handling routines. 

Upon entry to the $SAVRG routine, the program stack contains the return address to the original 
caller and the contents of Register 5 of the original caller. The $SAVRG routine pushes the 
contents of Registers 4 and 3 onto the stack, then pushes the current contents of Register 5 
(return address to the subroutine) onto the stack. 

The $SAVRG routine copies the original contents back into Register 5 and issues a coroutine 
call, in the form CALL @(SP)+, to swap control back to the subroutine. The coroutine call 
replaces the subroutine's return address with the return address to the $SAVRG routine. When 
control returns to the subroutine, the stack pointer points to $SAVRG's return address. The 
stack contains the following information: 
Return address to $SAVRG 
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Contents of Register 3 

Contents of Register 4 

Contents of Register 5 (contents of original caller) 

Return address to original caller 

The subroutine executes until a return instruction (RTS PC) is executed, which swaps control 
back to the $SAVRG routine. The contents of Registers 3 through 5 are restored (popped from 
the stack) and the $SAVRG routine returns to the original caller. 

Example 

The following source statements call the $SAVRG routine to save Registers 3 through 5: 



BUF: 



CBOM: 



1$: 



2$: 



.BLKW 


2 


MOV 


R0.R1 


BIC 


#177400, Rl 


MOV 


R3.R0 


cut 


R2 


MOV 


#BUF,R4 


CALL 


CBOM 


RETURN 




JSR 


R5.SSAVRG 


MOV 


#'0,R2 


MOV 


#10, R5 


MOV 


R1.R0 


MOV 


R5.R1 


CALL 


$DIV 


ADD 


R2.R1 


MOV 


Rl.-(SP) 


TST 


R0 


BEQ 


2$ 


CALL 


1$ 


MOVB 


(SP)+,(R4)+ 


MOV 


R4.R0 


RTS 


PC 



STRING BUFFER AREA 

COPY REGISTER 

MASK OFF HIGH BITS 

GET AREA TO PUT TERMINAL NUMBER IN 

SUPPRESS LEADING ZEROS 

OUTPUT STRING BUFFER 

CALL SUBROUTINE 



CALL $SAVRG 

SET ASCII BIAS 

SET RADIX FOR DIVISOR 

INPUT -> DIVIDEND 

RESET DIVISOR 

DIVIDE 

CONVERT REMAINDER TO ASCII 

PRESERVE CONVERTED REMAINDER 

NO QUOTIENT? (ALL DONE) 

YES, GO COPY TO OUTPUT BUFFER 

NO - DO NEXT DIGIT 

COPY A DIGIT TO OUTPUT 

STORE FINAL ADDRESS 

RETURN CONTROL TO $SAVRG 
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The $SAWR routine saves and subsequently restores Registers through 2 for a subroutine. 
The $SAWR routine functions as a coroutine that swaps control between itself, a subroutine, 
and the original caller. 

Format 

To call the $SAWR routine, include the following entries in your program: 

1. Enable the $SAWR routine to return control to the original caller by including the following 
instruction in the calling routine: 

CALL subroutine 

2. Call the $SAWR routine by including the following Jump to Subroutine instruction in the 
subroutine: 

JSR R2,$SAWR 
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3. Enable the subroutine to return control to the $SAWR routine by including the following 
return instruction in the subroutine: 

RTS PC 

Description 

Figure 2-1 illustrates the control swapping function performed by the register handling routines. 

Upon entry to the $SAWR routine, the program stack contains the return address to the original 
caller and the contents of Register 2 of the original caller. The $SAWR routine pushes the 
contents of Registers 1 and to the stack, then pushes the current contents of Register 2 (the 
return address to the subroutine) to the stack. 

The $SAWR routine copies the original contents back into Register 2 and issues a coroutine 
call, in the form CALL @(SP)+ / to swap control back to the subroutine. The coroutine call 
replaces the subroutine's return address with the return address to the $SAWR routine. When 
control returns to the subroutine, the stack pointer points to $SAWR's return address. The 
stack contains the following information: 

Return address to $SAWR 

Contents of Register 

Contents of Register 1 

Contents of Register 2 (contents of original caller) 

Return address to original caller 

The subroutine executes until a return instruction (RTS PC) is executed, which swaps control 
back to the $SAWR routine. The contents of Registers through 2 are restored (popped from 
the stack) and the $SAWR routine returns, by means of the RTS PC instruction, to the original 
caller. 

2.4 Save Registers 1-5 Routine (.SAVR1) 

The .SAVR1 routine saves and subsequently restores Registers 1 through 5 for a subroutine. 
The .SAVR1 routine functions as a coroutine that swaps control between itself, a subroutine, 
and the original caller. 

Format 

To call the .SAVR1 routine, include the following entries in your source program: 

1. Enable the .SAVR1 routine to return control to the original caller by including the following 
instruction in the calling routine: 

CALL subroutine 

2. Call the .SAVR1 routine by including the following Jump to Subroutine instruction in the 
subroutine: 

JSR R5..SAVR1 

3. Enable the subroutine to return control to the .SAVR1 routine by including the following 
return instruction in the subroutine: 

RTS PC 
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Description 

Upon entry to the .SAVR1 routine, the program stack contains the return address to the original 
caller and the contents of Register 5 of the original caller. The .SAVR1 routine pushes the 
contents of Registers 4, 3, 2, and 1, and the current contents of Register 5 (the return address 
to the subroutine) to the stack. 

The .SAVR1 routine copies the original contents back into Register 5 and issues a coroutine 
call, in the form CALL @(SP)+, to swap control back to the subroutine. The coroutine call 
replaces the subroutine's return address with the return address to the .SAVR1 routine. When 
control returns to the subroutine, the stack pointer points to .SAVRl's return address. The stack 
contains the following information: 

Return address to .SAVR1 

Contents of Register 1 

Contents of Register 2 

Contents of Register 3 

Contents of Register 4 

Register 5 (contents of original caller) 

Return address to original caller 

The subroutine executes until a return instruction (RTS PC) is executed, which swaps control 
back to the .SAVR1 routine. The contents of Registers 1 through 5 are restored (popped from 
the stack) and the .SAVR1 routine returns, by means of the RTS PC instruction, to the original 
caller. 

Example 

The following source statements call the .SAVR1 routine to save the contents of Registers 1 
through 5: 





.GLOBL 


PARSE.. FSRPT ; 




.MCALL 


FINIT$ ; 


FLOPN: 




: 




CALL 


NEWOPN ; 




BCC 


REGLOAD ; 




CALL 


0PERR$ 


REGLOAD 






NEWOPN : 


JSR 


R5..SAVR1 ; 




MOV 


fi#. FSRPT, Rl 




TST 


A.DFUI(Rl) ; 




BNE 


30$ ; 




FINIT$ 




30$ 


CALL 


REGLOAD ; 




CALL 


.PARSE ; 




RETURN 





0PERR$: 



DEFINE FCS ENTRIES 

GET FCS MACRO DEFINITION 

CALLING ROUTINE LOADS FILE DATA IN REGISTERS 

OPEN NEW COMMAND FILE 
BR IF NO ERROR 
OPEN ERROR ROUTINE 

LOAD REGISTERS ROUTINE 

SAVE REGISTERS i-5 

POINTER TO FILE AREA 

HAS IT BEEN INITIALIZED? 

BRANCH IF YES 

IF NOT, INITIALIZE FILE SYSTEM 

LOAD REGISTERS 

FILL IN FNB WITH FILE DATA 

ERROR ROUTINE 
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Chapter 3 

Arithmetic Routines 



The system library contains four arithmetic routines that perform unsigned integer multiplication 
and division. This chapter describes the use and function of these arithmetic routines. 

3. 1 Integer Arithmetic Routines 

The following routines perform arithmetic operations on 16-bit unsigned integer values: 

• The Integer Multiply Routine ($MUL), which multiplies integer values 

• The Integer Divide Routine ($DIV), which divides integer values 

3.1.1 Integer Multiply Routine ($MUL) 

The $MUL routine multiplies two single-word unsigned integer input values to produce an 
unsigned double-word product. 

Format 

CALL $MUL 

Input 

multiplier 

In Register 0: a single-word unsigned integer 

multiplicand 

In Register 1: a single-word unsigned integer 

Output 

product (high-order) 

In Register 0: the high-order part of the result 

product (low-order) 

In Register 1: the low-order part of the result 



Arithmetic Routines 3-1 



The $MUL routine preserves Registers 2 through 5 of the calling task. It does not return any 
error indications to the caller. 

Example 

The following source statements call the $MUL routine to perform multiplication and store the 
results in the buffer WORK: 



WORK: .BLKW 2 



MOV #1200, R0 

MOV #36, Rl 

CALL $MUL 

MOV RO.WORK 

MOV R1.W0RK+2 



OUTPUT BUFFER 

PUTS MULTIPLIER IN REGISTER 

PUTS THE MULTIPLICAND IN REGISTER 1 

CALLS $MUL ROUTINE 

SAVES HIGH-ORDER PART OF RESULT 

SAVES LOW-ORDER PART OF RESULT 



3.1.2 Integer Divide Routine ($DIV) 

The $DIV routine performs unsigned integer division. 



Format 




CALL $DIV 




Input 




dividend 




In Register 0: 


an unsigned integer 


divisor 




In Register 1: 


an unsigned integer 


Output 




quotient 




In Register 0: 


the quotient 



remainder 

In Register 1: the remainder 

The $DIV routine preserves Registers 2 through 5 of the calling task. It does not return any 
error indications to the caller. 

Example 

The following source statements call the $DIV routine to perform division and store the results 
in Registers and 1: 



FRACTN: .WORD 


1 


; BUFFER FOR REM, 


MOV 


#36. ,R0 


; SET DIVIDEND 


MOV 


#8.,R1 


; SET DIVISOR 


CALL 


$DIV 


; DIVIDE 


MOV 


Ri, FRACTN 


; SAVE REMAINDER 



3-2 Arithmetic Routines 



3.2 Double-Precision Arithmetic Routines 

The following routines perform double-precision arithmetic operations: 

• The Double-Precision Multiply Routine ($DMUL), which multiplies an unsigned double- 
precision value by a single-precision multiplier to produce a double-precision product 

• The Double-Precision Divide Routine ($DDIV), which divides an unsigned double-precision 
dividend by an unsigned single-precision divisor to produce a double-precision result 

3.2.1 Double-Precision Multiply Routine ($DMUL) 

The $DMUL routine multiplies an unsigned double-precision value by an unsigned single- 
precision value to produce an unsigned double-precision product. 

Format 

CALL $DMUL 

Input 

multiplier 

In Register 0: an unsigned single-precision magnitude value 

multiplicand (high-order) 

In Register 2: the high-order part of an unsigned double-precision magnitude value 

multiplicand (low-order) 

In Register 3: the low-order part of the unsigned double-precision magnitude value 

Output 

product (high-order) 

In Register 0: the high-order part of the product 

product (low-order) 

In Register 1: the low-order part of the product 

The $DMUL routine preserves Registers 4 and 5 of the calling task, clears the C bit, and destroys 
the contents of Registers 2 and 3 upon return to the caller. The $DMUL routine does not return 
any error indications to the caller. 

Example 

The following source statements call the $DMUL routine to multiply the number stored in 
Registers 2 and 3 by 127 10 and store the result in Registers and 1: 



MOV 


R5.R2 


HIGH-ORDER PART OF MULTIPLICAND 


MOV 


R4.R3 


LOW-ORDER PART OF MULTIPLICAND 


MOV 


#127., RO 


MULTIPLIER 


CALL 


$DMUL 


MULTIPLY BY 127. 
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3.2.2 Double-Precision Divide Routine ($DDIV) 

The $DDIV routine divides an unsigned double-predsion integer dividend by an unsigned 
single-precision (15-bit) divisor to produce an unsigned double-precision result. 

Format 

CALL $DDIV 

Input 

divisor 

In Register 0: an unsigned double-precision integer 

dividend (high-order) 

In Register 1: the high-order part of an unsigned single-precision integer 

dividend (low-order) 

In Register 2: the low-order part of an unsigned single-precision integer 

Output 

remainder 

In Register 0: the remainder 

quotient (high-order) 

In Register 1: the high-order part of the quotient 

quotient (low-order) 

In Register 2: the low-order part of the quotient 

The $DDIV routine preserves the contents of Registers 3 through 5 of the calling task. The 
$DDIV routine does not return any error conditions to the caller. 

Example 

The following source statements call the $DDIV routine to perform division and store the results 
in Registers 0, 1, and 2: 

BUFFER TO STORE HIGH- ORDER OF DIVIDEND 
BUFFER TO STORE HIGH- ORDER OF QUOTIENT 
BUFFER FOR REMAINDER 

PUT DIVISOR IN REGISTER 

SET UP HIGH-ORDER PART OF DIVIDEND 

SET UP LOW-ORDER PART OF DIVIDEND 

CALL $DDIV ROUTINE 

PUT HIGH-ORDER PART OF QUOTIENT IN BUFFER 

PUT LOW-ORDER PART OF QUOTIENT IN BUFFER 

PUT REMAINDER IN RMAIN 



DVD: 


.BLKW 


2 


QUOT: 


.BLKW 


2 


RMAIN 


: .BLKW 


1 




MOV 


#150. R0 




MOV 


DVD.R1 




MOV 


DVD+2.R2 




CALL 


$DDIV 




MOV 


R1.QU0T 




MOV 


R2.QU0T+2 




MOV 


RO. RMAIN 
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Chapter 4 

Input Data Conversion Routines 



The input data conversion routines accept ASCII data as input and convert it to the specified 
numeric representation. The following three types of routines perform input data conversion: 

• ASCII to binary double-word conversion routines, which accept ASCII decimal or octal 
input numbers and convert them to double-word binary numbers 

• ASCII to binary conversion routines, which accept ASCII decimal or octal input numbers 
and convert them to single-word binary numbers 

• ASCII to Radix-50 conversion routines, which accept the Radix-50 set of ASCII characters 
as input and convert them to Radix-50 internal format 

4. 1 ASCII to Binary Double-Word Conversions 

The following system library routines convert ASCII input numbers to double-word binary 
numbers: 

• The Decimal to Binary Double-Word Routine (.DD2CT), which accepts ASCII decimal 
numbers as input and converts them to double-word binary format 

• The Octal to Binary Double-Word Routine (.OD2CT), which accepts ASCII octal numbers 
as input and converts them to double-word binary format 

4.1.1 Decimal to Binary Double-Word Routine (.DD2CT) 

The .DD2CT routine converts a signed ASCII decimal number string to a double-length (2-word) 
signed binary number. 

Format 

CALL .DD2CT 
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Input 

output address 

In Register 3: the address of the 2-word output field in which the converted number is to 
be stored 

number input characters 

In Register 4: the number of characters in the string to be converted 

input string address 

In Register 5: the address of the character string to be converted 

Output 

binary result (high-order) 

In word 1 of the output field: the high-order 16 bits of the converted number 

binary result (low-order) 

In word 2 of the output field: the low-order 16 bits of the converted number 

Condition Code 

C bit = Clear if conversion was successful 

C bit = Set if an illegal character was found and conversion was incomplete 

Description 

The .DD2CT routine accepts leading plus (+) or minus (-) signs and a trailing period ( . ) in the 
string to be converted. A preceding pound sign (#) forces octal conversion; a pound sign and a 
period in the same input string is invalid. The numbers to 9 are acceptable characters in the 
decimal number string itself. Any other characters in the string will cause the .DD2CT routine 
to terminate the conversion procedure. The value range of a decimal number to be converted 
is -2 31 to +2 31 -1. 

The .DD2CT routine saves and restores all of the calling task's registers. 

Example 

The following source statements call the .DD2CT routine to convert an ASCII decimal number 
string (pointed to by buffer ICHR), store the binary result in the address pointed to by buffer 
BOUT, and check the results upon return: 



GET ADDRESS OF THE 2-WORD OUTPUT FIELD 

GET THE NUMBER OF INPUT CHARACTERS 

GET ADDRESS OF THE INPUT CHARACTER STRING 

CONVERT THE STRING 

BRANCH IF C BIT SET (CONVERSION WAS NOT SUCCESSFUL) 

PROGRAM CONTINUES 

CALL ROUTINE TO OUTPUT ERROR MESSAGE 



ICHR: 


.ASCII 
.EVEN 


/ 1234567./ 


BOUT: 


.BLKW 


2 




MOV 


#B0UT,R3 




MOV 


#10, R4 




MOV 


*ICHR,R5 




CALL 


.DD2CT 




BCS 


100$ 


100$: 


CALL ERR 
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4.1.2 Octal to Binary Double-Word Routine (.OD2CT) 

The .OD2CT routine converts an ASCII octal number string to a double-length (2-word) binary 
number. 

Format 

CALL .0D2CT 

Input 

output address 

In Register 3: the address of the 2-word output field in which the converted number is to 
be stored 

number input characters 

In Register 4: the number of characters in the string to be converted 

input string address 

In Register 5: the address of the character string to be converted 

Output 

binary result (high-order) 

In word 1 of the output field: the high-order 16 bits of the converted number 

binary result (low-order) 

In word 2 of the output field: the low-order 16 bits of the converted number 

Condition Code 

C bit = Clear if conversion was successful 

C bit = Set if an illegal character was found and conversion was incomplete 

Description 

The .OD2CT routine accepts leading plus ( + ) or minus (-) signs and a trailing period (.) in 
the string to be converted. A preceding pound sign ( # ) is accepted but unnecessary; a pound 
sign and a period in the same input string is invalid. A trailing period forces decimal conversion. 
(This is because the .OD2CT routine is an entry point in the .DD2CT routine, which converts 
decimal number strings to binary double-word values (see Section 4.1.1).) Acceptable characters 
in the octal number string itself are the numbers to 7. 

The .OD2CT routine will terminate the conversion process if you use any other characters in 
the ASCII octal number string. 

The value range of an octal number you can convert is — 2 31 to +2 31 — 1. 

The .OD2CT routine saves and restores all of the calling task's registers. 
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Example 

The following source statements call the .OD2CT routine to convert an ASCII octal number 
string (pointed to by buffer ICHR), store the binary result in the address pointed to by buffer 
BOUT, and check the results upon return: 



ICHR: 


.ASCII 
.EVEN 


/2461357/ 


BOUT: 


.BLKW 


2 




MOV 


#B0UT,R3 




MOV 


#7,R4 




MOV 


#ICHR,R5 




CALL 


.0D2CT 




BCS 


100$ 


100$: 


CALL ERR 



GET ADDRESS J)F THE 2-WORD OUTPUT 

GET THE NUMBER OF INPUT CHARACTERS 

GET ADDRESS OF THE INPUT CHARACTER STRING 

CONVERT THE STRING 

BRANCH IF C BIT SET (INPUT STRING 

CONVERSION WAS NOT SUCCESSFUL) 
IF C BIT CLEAR, CONVERSION WAS SUCCESSFUL 

AND THE PROGRAM CONTINUES 
CALL ROUTINE TO OUTPUT ERROR MESSAGE 



4.2 ASCII to Binary Conversions 

The following routines convert unsigned ASCII input numbers to single-word unsigned binary 
numbers: 

• The Decimal to Binary Conversion Routine ($CDTB), which accepts ASCII decimal numbers 
as input and converts them to single-word binary format 

• The Octal to Binary Conversion Routine ($COTB), which accepts ASCII octal numbers as 
input and converts them to single-word binary format 

These routines call the Integer Multiply Routine ($MUL) to perform the multiplication required 
for the conversion. 

4.2. 1 Decimal to Binary Conversion Routine ($CDTB) 

The $CDTB routine converts an unsigned ASCII decimal number to binary format. 
Format 

CALL $CDTB 

Input 

input buffer address 

In Register 0: the address of the first byte of the ASCII decimal character string to be 
converted 

Output 

next byte address 

In Register 0: the address of the next byte of the input buffer 

binary number 

In Register 1: the converted number 
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terminator 



ninator 

In Register 2: the terminating character of the input buffer 



Description 

The numbers to 9 are valid characters in the input decimal number. All other input characters 
are invalid and are not converted by this routine. The end of a string of numbers must be 
marked by a terminating character, which may be any ASCII character except the numbers 
to 9. Examples of terminating characters are a blank, tab character, alphabetic character, and 
special symbol. Leading blanks and tab characters are ignored. 

The maximum value of a decimal number that can be converted by the $CDTB routine is 
65,535. Numbers of greater value will cause indeterminate results since the $CDTB routine does 
not check the value range of an input number. Also, the routine does not return a significant 
Condition Code setting to the calling task. 

Because the $CDTB routine returns the address of the next byte in the input buffer to the calling 
task, you can convert successive strings by setting up a processing loop back to the CALL 
$CDTB statement (see the example for this routine). 

$CDTB calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 

Note 

You can determine, in the task, whether an input string was successfully 
converted by testing the contents of Register 2. If the contents are other than 
the expected terminating character, the conversion was incomplete because the 
routine found an invalid character in the input string. 

Example 

The following source statements define a processing loop, using the $CDTB routine, to convert a 
series of ASCII decimal character strings to binary numbers. This example uses the tab character 
as the terminating character of each string and the space character as the terminating character 
of the input buffer. If converted successfully, the binary numbers will be stored in the buffer 
BNUM: 

IBUF: .ASCII /123/<ll>/4567/<ll>/89/<li>/87654/<40> 

.EVEN 
BNUM: .BLKW 4 ; BUFFER FOR CONVERTED NUMBERS 
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MOV #BNUM,R4 

MOV #IBUF,RO 

LOOP: CALL $CDTB 

MOV Ri.(R4)+ 

CMP #11, R2 

BEQ LOOP 



CMP #40, R2 
BEQ 10$ 
JMP ERR 



GET THE OUTPUT BUFFER ADDRESS 

SET UP INPUT BUFFER ADDRESS 

CONVERT THE STRING 

SAVE CONVERTED STRING 

COMPARE ASCII TAB (HT) VALUE TO TERMINATING 

CHARACTER RETURNED IN REGISTER 2 
IF EQUAL. STRING SUCCESSFULLY CONVERTED. 

GO BACK THROUGH LOOP TO CONVERT NEXT INPUT 
STRING POINTED TO BY REGISTER 
COMPARE SPACE VALUE (40) WITH TERMINATING 

CHARACTER IN REGISTER 2 
IF EQUAL, CONTINUE PROGRAM (ALL INPUT 

HAS BEEN CONVERTED SUCCESSFULLY) 
IF NOT EQUAL, ILLEGAL CHARACTER IN INPUT 

STRING CAUSED CONVERSION TO TERMINATE; HENCE 
INPUT IS ERRONEOUS; GO TO ERROR ROUTINE 
PROGRAM CONTINUES 



10$: 

4.2.2 Octal to Binary Conversion Routine ($COTB) 

The $COTB routine converts an unsigned ASCII octal number to binary format. 
Format 

CALL $COTB 

Input 

input buffer address 

In Register 0: the address of the first byte of the ASCII octal character string to be converted 

Output 

next byte address 

In Register 0: the address of the next byte of the input buffer 

binary number 

In Register 1: the converted number 

terminator 

In Register 2: the terminating character of the input buffer 

Description 

The characters to 7 are valid in the input octal number. The maximum value of an octal 
number that can be converted by the $COTB routine is 177777. The end of a string must be 
marked by a terminating character, which may be any ASCII character except the numbers 
to 7. Examples of terminating characters are a blank, tab character, alphabetic character, and 
special symbol. Leading blanks and tab characters are ignored. 

$COTB calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 

Note 

You can determine, in the task, whether an input string was successfully 
converted by testing the contents of Register 2. If the contents are other than 
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the expected terminating character, the conversion was incomplete because the 
routine found an invalid character in the input string. 

Example 

The following source statements define a processing loop, using the $COTB routine, to convert 
a series of ASCII octal character strings to binary numbers. The example uses the tab character 
as the terminating character of each string and the space character as the terminating character 
of the input buffer. If converted successfully, the binary numbers will be stored in the buffer 
BNUM: 

IBUF: .ASCII /012/<ll>/3456/<il>/76/<il>/54321/<40> 

.EVEN 
BNUM: .BLKW 4 ; BUFFER FOR CONVERTED STRINGS 



LOOP: 



MOV #BNUM,R4 

MOV #IBUF,RO 

CALL $C0TB 

MOV R1,(R4) + 

CMP #11 ,R2 

BEQ LOOP 



CMP #40, R2 
BEQ 10$ 
JMP ERR 



10$: 



GET OUTPUT BUFFER ADDRESS 

SET UP INPUT BUFFER ADDRESS 

CONVERT THE STRING 

SAVE CONVERTED STRING 

COMPARE ASCII TAB (HT) VALUE TO TERMINATING 

CHARACTER RETURNED IN REGISTER 2 
IF EQUAL, STRING SUCCESSFULLY CONVERTED, 

GOES BACK THROUGH LOOP TO CONVERT NEXT INPUT 
STRING POINTED TO BY REGISTER 
COMPARES SPACE VALUE (40) WITH TERMINATING 

CHARACTER IN REGISTER 2 
IF EQUAL, CONTINUES PROGRAM (ALL INPUT 

HAS BEEN CONVERTED SUCCESSFULLY) 
IF NOT EQUAL, ILLEGAL CHARACTER IN INPUT 

STRING CAUSED CONVERSION TO TERMINATE; HENCE 
INPUT IS ERRONEOUS; GOES TO ERROR ROUTINE 
PROGRAM CONTINUES 



4.3 ASCII to Radix-50 Conversions 

The following routines convert ASCII alphanumeric input characters to 16-bit Radix-50 values: 

• The ASCII to Radix-50 Conversion Routine ($CAT5), which accepts input characters from 
the ASCII character Radix-50 subset and converts them to Radix-50 format 1 

• The ASCII with Blanks to Radix-50 Conversion Routine ($CAT5B), which accepts input 
characters from the ASCII character Radix-50 subset and blank characters and converts 
them to Radix-50 format 1 

Both routines call the Integer Multiply Routine ($MUL) to perform the multiplication required 
for the conversion. 



See the PDP-11 MACRO-11 Language Reference Manual for a complete listing of the Radix-50 character set and ASCII equivalents. 
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4.3. 1 ASCII to Radix-50 Conversion Routine ($CAT5) 

The $CAT5 routine converts up to three ASCII characters to a 16-bit Radix-50 value. 
Format 

CALL SCAT5 

Input 

input buffer address 

In Register 0: the address of the first character in the ASCII string you want to convert 

period disposition flag 

In Register 1, one of the following values: 

Rl = if the period is a terminating character 

Rl = 1 to specify that the period is a valid character to be converted to Radix-50 

Output 

next input character 

In Register 0: the address of the next character of the input string 

Radix-50 value 

In Register 1: the converted Radix-50 value 

terminator 

In Register 2: the terminating character or the invalid character that caused termination 

Condition Code 

C bit = Clear if conversion was complete 

C bit = Set if conversion was incomplete 

Description 

The following characters are valid in the ASCII string to be converted: 

• The alphabetic characters A to Z 

• The numeric characters to 9 

• The dollar sign ( $ ) and period ( . ) 

For complete conversion, the string must contain three valid characters. If the string contains 
fewer than three valid characters, the $CAT5 routine will convert them but will set the C bit 
to indicate an incomplete conversion. Invalid characters cause the $CAT5 routine to terminate 
conversion. In this case, the output will be the valid character or characters and trailing blank 
or blanks, in binary format. 

A blank character (space) in the ASCII character string causes the $CAT5 routine to terminate. 
If you include blanks as valid characters in the string, call the $CAT5B routine to do the 
conversion. 
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Since the address of the next character in the input string is returned in Register 0, you can 
convert successive strings by resetting Register 1 and setting up a processing loop back to the 
CALL $CAT5 statement. 

The $CAT5 routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task. 

Note 

You can determine, in the task, whether conversion was complete by testing 
the C bit in the Condition Code or the contents of Register 2. 

Example 

The following source statements define a subroutine that calls the $CAT5 routine to convert 
ASCII input data to Radix-50 format: 



ASDAT: .ASCII /ABC.DEF 
.EVEN 

RAD5: .BLKW 3. 
.EVEN 

MOV #RAD5,R4 
MOV #3,115 
MOV #ASDAT,R0 

1$: CLR Rl 

CALL $CAT5 
BCC 2$ 
JMP INER 

2$: MOV R1,(R4)+ 
DEC R5 

BGT 1$ 



HI J./ ; STRINGS TO BE CONVERTED 
; OUTPUT BUFFER 



GET OUTPUT ADDRESS 

SET LIMIT TO LOOP 

SET UP THE ADDRESS OF THE FIRST ASCII CHARACTER 

SPECIFY THAT PERIOD IS CONVERSION TERMINATOR 

CONVERT ASCII RADIX-50 

BRANCH IF C BIT IS CLEAR (CONVERSION COMPLETE) 

JUMP TO INPUT ERROR ROUTINE IF 

C BIT IS SET (CONVERSION INCOMPLETE) 
STORE CONVERTED CHARACTER 

PROCESS NEXT STRING 



4.3.2 ASCII with Blanks to Radix-50 Conversion Routine ($CAT5B) 

The $CAT5B routine converts an ASCII 3-character string, including blank characters, to a 16-bit 
Radix-50 value. 

Format 

CALL $CAT5B 

Input 

input buffer address 

In Register 0: the address of the first character in the ASCII string you want to convert 

period disposition flag 

In Register 1, one of the following values: 
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Rl = if the period is a terminating character 

Rl - 1 to specify that the period is a valid character to be converted to Radix-50 

Output 

next input character 

In Register 0: the next character of the input string 

Radix-50 value 

In Register 1: the converted Radix-50 value, one to three characters in length 

terminator 

In Register 2: the terminating character or the invalid character that caused termination 

Condition Code 

C bit = Clear if conversion was complete 

C bit = Set if conversion was incomplete 

Description 

The following characters are valid in the ASCII string to be converted: 

• The alphabetic characters A to Z 

• The numeric characters to 9 

• The dollar sign ($ ), period ( . ), and blank (space) 

For complete conversion, the string must contain three valid characters. If the string contains 
fewer than three valid characters, the $CAT5B routine will convert them but will set the C bit 
to indicate an incomplete conversion. Invalid characters cause the $CAT5B routine to terminate 
conversion. In this case, the output will be the valid character or characters and trailing blank 
or blanks, in binary format. 

Since the address of the next character in the input string is returned in Register 0, you can 
convert successive strings by resetting Register 1 and setting up a processing loop back to the 
CALL $CAT5B statement. 

$CAT5B calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 

Note 

You can determine, in the task, whether conversion was complete by testing 
the C bit in the Condition Code or the contents of Register 2. 

Example 

The following source statements call the $CAT5B routine to convert a 3-character ASCII string 
to Radix-50 format: 
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INSTR: 



.ASCII 


/IND/ 


.BYTE 


15 


.EVEN 




MOV 


INSTR, RO 


MOV 


#1,R1 


CALL 


$CAT5B 


BCC 


10$ 


CMPB 


#15. R2 


BEQ 


10$ 


CALL 


SERR 



10$: 



ASCII INPUT STRING 
STRING TERMINATOR 



POINT TO THE ASCII INPUT STRING 
SPECIFY PERIOD IS VALID CHARACTER 
CONVERT IT TO RADIX-50 
WERE CHARACTERS CONVERTED? 
NO — WAS TERMINATOR A <CR> ? 
EQ — YES 

NO. CALL SYNTAX ERROR ROUTINE 
PROGRAM CONTINUES 
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Chapter 5 

Output Data Conversion Routines 

The output data conversion routines convert internally stored numeric data to ASCII characters. 
The following four groups of routines convert output data: 

• Binary to decimal conversion routines, which convert binary data to one of the following 
formats: 

— 2-digit day date, in the range 01 to 31 

— 5-digit unsigned decimal magnitude number 

— 5-digit signed decimal number 

— Decimal number up to nine digits in length 

• Binary to octal conversion routines, which convert binary numbers to one of the following 
octal numbers: 

— 6-digit unsigned octal magnitude number 

— 6-digit signed octal number 

— 3-digit octal number 

• A general-purpose binary conversion routine, which converts binary data to ASCII format. 
Note that the preceding conversion routines format their output according to internally- 
defined conversion parameters. The $CBTA routine allows you to determine the format of 
the output by specifying the conversion parameters. You can call this routine directly, or 
you may call it indirectly when you use the binary to decimal or octal routines. These 
routines pass predefined conversion parameters to the $CBTA routine. 

• A Radix-50 to ASCII conversion routine, which converts a Radix-50 value to a 3-character 
ASCII string 

The output data routines described in this chapter are called by the Edit Message Routine 
($EDMSG; described in Chapter 6) to convert data to be formatted for output to printers or 
display devices. 
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5. 1 Binary to Decimal Conversions 

The following four system library routines convert internally formatted binary numbers to 
external ASCII decimal format: 

• Binary Date Conversion Routine ($CBDAT), which converts an internally stored binary date 
to a 2-digit decimal number 

• Convert Binary to Decimal Magnitude Routine ($CBDMG), which converts an internally 
stored binary number to a 5-digit unsigned ASCII decimal magnitude value 

• Convert Binary to Signed Decimal Routine ($CBDSG), which converts an internally stored 
binary number to a 5-digit signed ASCII decimal number 

• Convert Double-Precision Binary to Decimal Routine ($CDDMG), which converts a double- 
precision, unsigned binary number to an ASCII decimal number of nine or fewer digits 

These routines use predefined conversion parameters that are passed to the general-purpose 
conversion routine ($CBTA), which performs the actual binary to ASCII conversion. 

Note that these routines do not add an extra space for the minus sign (-) to the predefined 
field-width parameter. If you are converting a negative number, expect that one of the spaces 
in the output area will be used for the minus sign. 

5. 1 . 1 Binary Date Conversion Routine ($CBDAT) 

The $CBDAT routine converts an internally stored binary date to a 2-digit unsigned decimal 
number. 

Format 

CALL $CBDAT 
The $CBDAT routine uses the following predefined conversion parameters: 
Radix = 10 

Field width = 2 characters 
Sign flag = UNSIGNED 

Input 

output address 

In Register 0: the starting address of the output area that will store the converted 2-byte 
date 

input date 

In Register 1: the date (a binary value in the range 01 to 31) 

zero suppression indicator 

In Register 2, one of the following values: 
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R2 = to specify suppression of leading zeros in the converted date (the date will be 
left-justified) 

R2 = Nonzero to specify no suppression of leading zeros 

Output 

converted date 

In the specified output area: the converted day date (in ASCII decimal format) 

next output address 

In Register 0: the next available address (the pointer to the location following the last digit 
stored) 

Description 

The $CBDAT routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion 
Routine ($CBTA), which performs the actual conversion of the binary number. 

The $CBDAT routine calls the $SAVRG routine to save and restore Registers 3 through 5 of 
the calling task, and destroys the contents of Registers 1 and 2. The $CBDAT routine does not 
return any error conditions to the caller. 

Example 

The following source statements call the $CBDAT routine to convert a binary date in the buffer 
BDAT and store the converted date in the buffer ASDAT: 

; OUTPUT BUFFER 

; INPUT — BINARY DATE 

; PUTS THE ADDRESS OF OUTPUT AREA IN REGISTER 

; PUTS THE BINARY DATE, AT BDAT. IN REGISTER 1 

; CLEARS REGISTER 2 TO ZERO TO SPECIFY THAT LEADING 
; ZEROS ARE TO BE SUPPRESSED 

CALL $CBDAT ; CALLS THE $CBDAT ROUTINE 

5.1.2 Convert Binary to Decimal Magnitude Routine ($CBDMG) 

The $CBDMG routine converts an internally stored binary number to a 5-digit unsigned ASCII 
decimal magnitude number. 

Format 

CALL $CBDMG 
The $CBDMG routine uses the following predefined conversion parameters: 



ASDAT: 


.BLKB 
.EVEN 


2 


BDAT: 


WORD 


1 




MOV 


#ASDAT,R0 




MOV 


BDAT.R1 




CLR 


R2 
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Radix = 10 

Field width = 5 characters 

Sign flag = UNSIGNED 

Input 

output address 

In Register 0: the starting address of the output area that will contain the converted 5-digit 
number 

input number 

In Register 1: the unsigned binary number you want to convert 

zero suppression indicator 

In Register 2, one of the following values: 

R2 = to specify suppression of leading zeros in the converted number (the number will 
be left-justified) 

R2 = Nonzero to specify no suppression of leading zeros 

Output 

result 

In the specified output area: the converted number, a maximum of five digits in length 

next output address 

In Register 0: the next available address in the output area (the pointer to the location 
following the last digit stored) 

Description 

The $CBDMG routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion 
Routine ($CBTA), which performs the actual conversion of the binary number. 

The $CBDMG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of 
the calling task. It destroys the contents of Registers 1 and 2. The $CBDMG routine does not 
return error conditions to the caller. 

Example 

The following source statements call the $CBDMG routine to convert a binary number stored 
in the buffer $IEXT and store the converted 5-digit ASCII decimal magnitude number in the 
buffer .TEXT: 

.TEXT: .BLKB 5 ; OUTPUT BUFFER 

.EVEN 
$IEXT: .WORD 2765. ; INPUT VALUE 
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MOV #.TEXT,RO ; GET OUTPUT BUFFER 

MOV $IEXT,Ri ; GET BINARY VALUE 

CLR R2 ; SUPPRESS ZEROS 

CALL SCBDMG ; CONVERT TO ASCII (DECIMAL) 

5.1.3 Convert Binary to Signed Decimal Routine ($CBDSG) 

The $CBDSG routine converts an internally stored binary number to a 5-digit signed ASCII 
decimal number. 

Format 

CALL $CBDSG 

The $CBDSG routine uses the following predefined conversion parameters: 
Radix - 10 

Field width = 5 characters 

Sign flag = SIGNED 

Input 

output address 

In Register 0: the starting address of the output area that will store the converted 5-digit 
number 

input number 

In Register 1: the binary number to be converted 

zero suppression indicator 

In Register 2, one of the following values: 

R2 = to suppress leading zeros in the converted number (the output number will be 
left-justified) 

R2 = Nonzero to specify no suppression of leading zeros 

Output 

result 

In the specified output area: the converted number, a maximum of five digits in length 

next output address 

In Register 0: the next available address in the output area (the pointer to the location 
following the last digit stored) 

Description 

The $CBDSG routine automatically pushes the predefined conversion parameters on the stack. 
It then passes the conversion parameters in Register 2 to the General Purpose Binary to ASCII 
Conversion Routine ($CBTA), which performs the actual conversion of the binary number. 

The $CBDSG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task, and does not save the contents of Registers 1 or 2. The $CBDSG routine does not 
return error conditions to the caller. 
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FILERR: MOVB 


F.ERR(RO),Rl 


MOV 


#ER2NUM,R0 


CLR 


R2 


CALL 


$CBDSG 


MOVB 


#'.,(RO)+ 



Example 

The foUowing source statements call the $CBDSG routine to convert a binary value stored in 
the buffer F.ERR and store the converted 5 -digit ASCII decimal number in the buffer ER2NUM: 

ER2: .ASCII $1/0 ERROR C0DE:$ ; ERROR MESSAGE 
ER2NUM: .BLKB 5 ; OUTPUT BUFFER 

.EVEN 

GET ERROR CODE TO CONVERT 
POINT TO OUTPUT BUFFER 
SUPPRESS LEADING ZEROS 
CONVERT ERROR CODE 
PUT IN DECIMAL POINT 

5.1.4 Convert Double-Precision Binary to Decimal Routine ($CDDMG) 

The SCDDMG routine converts a double-precision, unsigned binary number to an unsigned 
ASCII decimal number, up to nine digits, less than or equal to 65,536x1 4 . If the number 
contains more than nine digits, the routine inserts a string of five ASCII asterisk symbols in the 
output area. 

Format 

CALL $CDDMG 

Input 

output address 

In Register 0: the starting address of the output area 

input address 

In Register 1: the address of the 2-word input area containing the double-precision number 

zero suppression indicator 

In Register 2, one of the following values: 

R2 = to specify suppression of leading zeros in the converted date (the date will be 
left-justified) 

R2 = Nonzero to specify no suppression of leading zeros 

Note 

If the five most significant digits are zeros, they will be suppressed automatically, 
regardless of the setting of the suppression indicator. 

Output 

result 

In the output area: the converted ASCII number 

next output address 

In Register 0: the pointer to the next available address in the output storage area 
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Note 

If the number was converted successfully, the output area will contain from 
four to nine digits. If the conversion attempt results in a decimal number 
greater than 65,536xl0 4 or longer than nine digits, the $CDDMG routine 
prints a string of five ASCII asterisks in the output area. 

Description 

The $CDDMG routine performs the following actions: 

• Calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task 

• Calls the $DDIV routine to perform the double-precision division 

• Calls the $CBTA routine to perform the actual ASCII conversion 

• Destroys the contents of Registers 1 and 2 

Example 

The following source statements call the $CDDMG routine to convert a double-precision number, 
pointed to by the buffer DPWRD, and store the converted ASCII decimal number in the buffer 
ASDN: 



ASDN: .BLKB 9. 

.EVEN 
DPWRD: .BLKW 2 



MOV 
MOV 

MOV 



#ASDN,RO 
#DPWRD.R1 

#4. ,R2 



CALL 


$CDDMG 


CMPB 


#'*,ASDN 


BNE 


10$ 


JMP 


ERR 



OUTPUT BUFFER 

INPUT BUFFER 

PUTS ADDRESS OF OUTPUT AREA IN REGISTER 

PUTS STARTING ADDRESS OF DOUBLE- 
PRECISION INPUT WORD IN REGISTER 1 

PUTS NONZERO IN REGISTER 2 (SETS THE ZERO 
INDICATOR FLAG TO 1) TO SPECIFY 
THAT LEADING ZEROS ARE NOT TO 
BE SUPPRESSED 

CALLS THE $CDDMG ROUTINE 

COMPARES AN ASCII ASTERISK SYMBOL WITH 
A BYTE OF THE CONVERTED NUMBER 

IF NOT EQUAL. CONVERSION WAS SUCCESSFUL 
AND PROGRAM CONTINUES 

IF EQUAL, JUMP TO ERROR ROUTINE ERR (MORE 
THAN NINE DIGITS WERE CONVERTED AND THE 
OUTPUT DATA IS INVALID) 



10$: 



Note 

The source statements also check the results and call an error routine if $CDDMG 
was not successful. 
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5.2 Binary to Octal Conversion 

The following three routines convert internally formatted binary numbers to external ASCII 
octal format: 

• Convert Binary to Octal Magnitude Routine ($CBOMG), which converts an internally stored 
binary number to a 6-digit unsigned ASCII octal magnitude number 

• Convert Binary to Signed Octal Routine ($CBOSG), which converts an internally stored 
binary number to a 6-digit signed ASCII octal number 

• Convert Binary Byte to Octal Magnitude Routine ($CBTMG), which converts an internally 
stored binary byte to a 3-digit unsigned ASCII octal number 

These routines pass predefined conversion parameters to the general-purpose conversion routine 
($CBTA), which performs the actual binary to ASCII conversion. 

Note that these routines do not add an extra space for the minus sign (-) to the predefined 
field-width parameter. If you are converting a negative number, expect that one of the spaces 
in the output area will be used for the minus sign. 

5.2. 1 Convert Binary to Octal Magnitude Routine ($CBOMG) 

The $CBOMG routine converts an internally stored binary number to a 6-digit unsigned ASCII 
octal magnitude number. 

Format 

CALL $CBOMG 

The $CBOMG routine uses the following predefined conversion parameters: 
Radix = 8 

Field width = 6 characters 

Sign flag - UNSIGNED 

Input 

output address 

In Register 0: the starting address of the output area in which the converted 6-digit number 
is to be stored 

input number 

In Register 1: the binary number you want to convert 

zero suppression indicator 

In Register 2, one of the following values: 

R2 = to specify suppression of leading zeros in the converted number (the number will 
be left-justified) 

R2 = Nonzero to specify no suppression of leading zeros 
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Output 
result 

In the specified output area: the converted number, a maximum of six digits in length 

next output address 

In Register 0: the next available address in the output area (the pointer to the location 
following the last digit stored) 

The $CBOMG routine does not return any error conditions to the caller. 

Description 

The $CBOMG routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion 
Routine ($CBTA), which performs the actual conversion of the binary number. 

The $CBOMG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of 
the calling task, and destroys the contents of Registers 1 and 2. 

Example 

The following source statements call the $CBOMG routine to convert a binary number stored in 
the buffer BNUM and store the converted 6-digit ASCII octal magnitude number in the buffer 
OCOUT: 



0C0UT: .BLKB 6 

.EVEN 
BNUM: .WORD 162710 

MOV #0C0UT,RO 
MOV BNUM.R1 
MOV #1,R2 



CALL $CB0MG 



OUTPUT BUFFER 

INPUT VALUE 

PUTS THE STARTING ADDRESS OF THE OUTPUT AREA IN REGISTER 
PUTS THE BINARY NUMBER TO BE CONVERTED IN REGISTER 1 
PUTS THE VALUE 1 IN REGISTER 2 (SETS THE ZERO 
INDICATOR FUG TO 1) TO SPECIFY THAT 

LEADING ZEROS ARE NOT TO BE SUPPRESSED 
CALLS THE $CB0MG ROUTINE 



5.2.2 Convert Binary to Signed Octal Routine ($CBOSG) 

The $CBOSG routine converts an internally stored binary number to a 6-digit signed ASCII 
octal number. 

Format 

CALL $CB0SG 

The $CBOSG routine uses the following predefined conversion parameters: 
Radix = 8 

Field width = 6 characters 

Sign flag = SIGNED 
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Input 

output address 

In Register 0: the starting address of the output area in which the converted 6-digit number 
will be stored 

input number 

In Register 1: the binary number to be converted 

zero suppression indicator 

In Register 2, one of the following values: 

R2 = to specify suppression of leading zeros in the converted number (the output num- 
ber will be left-justified) 

R2 = Nonzero to specify no suppression of leading zeros 

Output 

result 

In the specified output area: the converted signed number, a maximum of six digits in 
length 

next output address 

In Register 0: the next available address in the output area (the pointer to the location 
following the last digit stored) 

The $CBOSG routine does not return error conditions to the caller. 

Description 

The $CBOSG routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion 
Routine ($CBTA), which performs the actual conversion of the binary number. 

The $CBOSG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task, and destroys the contents of Registers 1 and 2. 

5.2.3 Convert Binary Byte to Octal Magnitude Routine ($CBTMG) 

The $CBTMG routine converts an internally stored binary byte to a 3-digit ASCII unsigned octal 
number. 

Format 

CALL $CBTMG 
The $CBTMG routine uses the following predefined conversion parameters: 
Radix = 8 

Field width = 3 characters 
Sign flag = UNSIGNED 
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Input 

output address 

In Register 0: the starting address of the output area in which the converted 3-digit number 
will be stored 

input binary byte 

In Register 1 (low-order byte): the binary byte to be converted 

zero suppression indicator 

In Register 2, one of the following values: 

R2 = to specify suppression of leading zeros in the converted number (the number will 
be left-justified) 

R2 = Nonzero to specify no suppression of leading zeros 

Output 

result 

In the specified output area: the converted number, a maximum of three digits in length 

next output address 

In Register 0: the next available address in the output area (the pointer to the location 
following the last digit stored 

The $CBTMG routine does not return error conditions to the caller. 

Description 

The $CBTMG routine pushes the predefined conversion parameters on the stack. It then passes 
the conversion parameters in Register 2 to the General Purpose Binary to ASCII Conversion 
Routine ($CBTA), which performs the actual conversion of the binary byte. 

The $CBTMG routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task, and destroys the contents of Register 2. In addition, $CBTMG clears the high-order 
byte of Register 1 (the low-order byte is unchanged). 

Example 

The following source statements call the $CBTMG routine to convert a binary number stored 
in the buffer TBUF and store the converted 3-digit ASCII octal number in the buffer BOUT: 



BOUT: 


.BLKB 
.EVEN 


3 


OUTPUT BUFFER 


TBUF: 


.BYTE 
.EVEN 


177 


INPUT BUFFER 




MOV 


#B0UT,RO 


ADDRESS OUTPUT BUFFER 




MOVB 


TBUF.R1 


GET BINARY CODE 




MOVB 


#1,112 


SPECIFY NO ZERO SUPPRESSION 




CALL 


$CBTMG 


CONVERT THE BINARY NUMBER TO OCTAL 
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5.3 Genera! Purpose Binary to ASCII Conversion Routine ($CBTA) 

The $CBTA routine converts internally stored binary numbers to ASCII decimal or octal numbers 
when called by the binary-to-decimal and binary-to-octal conversion routines described in 
Sections 5.1 and 5.2. 

Format 

CALL $CBTA 

Input 

output address 

In Register 0: the starting address of the output area in which the converted ASCII number 
will be stored 

input value 

In Register 1: the binary value to be converted 

conversion parameters 

In Register 2, the following options: 

Bits 0-7 (Low byte.) Must contain the conversion radix (2 to 16 decimal). 

Bit 8 Must contain the unsigned flag ( = 0) if unsigned value to be converted; or 

must contain the sign flag ( = 1) if signed value to be converted. 

(The minus sign is not counted in the output field width when you convert a 
negative signed number. The $CBTA routine will use a space in the output 
buffer for the minus sign.) 

Bit 9 Zero suppression flag = 0; or nonzero suppression flag = 1. 

Bit 10 Blank fill flag = 1 to specify replacement of leading zeros with blanks (only if 

nonzero suppression flag =1). 

Blank fill flag = to specify no replacement of leading zeros (if bit 9 = 1). 

(When the zero suppression flag = 0, the blank fill flag is ignored.) 

Bits 11-15 Must contain a numeric value from 1 to 32 specifying the field width. If you 
convert a negative signed number, remember to add a space in the field width 
for the minus sign. 

Output 

result 

In the specified output area: the converted number, from 1 to 32 digits in length 

next output address 

In Register 0: the next available address in the output area (the pointer to the location 
following the last digit stored) 

The $CBTA routine does not return any error conditions to the caller. 
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Description 

The $CBTA routine converts internally stored values according to the user-defined conversion 
parameters, which the calling routine passes as an input argument in Register 2. 

Note that the $CBTA routine does not add an extra space for the minus sign (-) to the predefined 
field-width parameter. If you are converting a negative number, expect that one of the characters 
in the output area will be used for the minus sign. 

The $CBTA routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
caller, and calls the $DIV routine to perform the required division. The $CBTA routine also 
destroys the contents of Registers 1 and 2. 

Example 

The following source statements set the conversion parameters, expressed in the number 15012g, 
which will determine the format of the output by $CBTA. The statements call the $CBTA routine 
to convert a binary value in Register 3 and store the ASCII result in buffer CASTR: 

CASTR: .BLKB 32. ; OUTPUT BUFFER 

.EVEN 

MOV RO.-(SP) ; SAVE REGS FOR CONVERT CALL 

MOV Ri.-(SP) 

MOV R2,-(SP) 

MOV #CASTR,RO ; ADDRESS TO CONVERT INTO 

MOV R3.R1 ; VALUE TO CONVERT 

MOV # 15012 ,R2 ; 3-DIGIT, NO ZERO SUPPRESSION 

CALL $CBTA ; CONVERT BINARY TO ASCII 

In this example, the binary expression of the value in Register 2 (0001101000001010) specifies 
that the output will have the the following conversion parameters: 
Conversion radix = 10j 

Sign flag = (unsigned value) 

NOSUP flag = 1 (no zero suppression) 

Blank fill flag = (no replacement of leading zeros with blanks) 

Field width = 3 

5.4 Radix-50 to ASCII Conversion Routine ($C5TA) 

The $C5TA routine converts an internally stored 16-bit Radix-50 value to an ASCII character 
string. 

Format 

CALL $C5TA 
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Input 

output address 

In Register 0: the address that will point to the first byte of the converted string 

Radix-50 word 

In Register 1: the Radix-50 value you want to convert 

Output 

next output address 

In Register 0: the address of the next byte after the last character stored in the output area 

result 

In the specified output area: the converted ASCII 3-character string, stored in a maximum 
of three consecutive bytes 

The $C5TA routine does not return error conditions to the caller. It destroys the contents of 
Registers 1 and 2 and does not use Registers 3 through 5. 

Example 

The following source statements call the $C5TA routine to convert a Radix-50 number stored 
in the buffer CRNTS and store the ASCII string result in the buffer SCRPTR: 

CRNTS: .RAD50 /GEN/ ; EADIX VALUE 

SCRPTR: .BLKB 3 ; OUTPUT BUFFER 

.EVEN 



MOV #SCRPTR,R0 
MOV CRNTS. Rl 
CALL $C5TA 



SET OUTPUT BUFFER ADDRESS 
GET RADIX VALUE 
CONVERT IT 
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Chapter 6 

Output Formatting Routines 



The output formatting routines convert internally stored data to external ASCII characters and 
format the converted characters to produce readable output. The five output formatting routines 
are as follows: 

• The Uppercase Text Conversion Routine ($CVTUC), which converts lowercase ASCII text 
to uppercase 

• The Date String Conversion Routine ($DAT), which converts a 3 -word binary date to a 
9-character ASCII output string 

• The Alternate Date String Conversion Routine ($DAT), which converts a date to a user- 
defined ASCII format up to 25 characters long 

• The Time Conversion Routine ($TIM), which converts the binary time to an ASCII output 
string 

• The Edit Message Routine ($EDMSG), which converts internally stored data to the user- 
specified type of ASCII data (alphanumeric, octal, decimal) and formats the converted data 
to produce meaningful output for printing or display 

6. 1 Uppercase Text Conversion Routine ($CVTUC) 

The $CVTUC routine converts lowercase ASCII text to uppercase. The routine performs a 
byte-by-byte transfer of the input ASCII character string, converting all lowercase alphabetic 
characters to uppercase, and transferring all uppercase characters unchanged to the output string. 

Format 

CALL $CVTUC 

Input 

input address 

In Register 0: the address of the text string to be converted 
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output address 

In Register 1: the address of the output area for the uppercase string 

number Input bytes 

In Register 2: the number of bytes in the string to be converted 

Note 

The number of bytes may not be stated as 0. A statement of will cause 
$CVTUC to fail. 

Output 

result 

In the output area: the converted string 

next input address 

In Register 0: a pointer to the next available address in the input area 

next output address 

In Register 1: a pointer to the next available address in the output area 

Description 

The $CVTUC routine converts all ASCII alphabetic characters in the input string to uppercase. 
Any other characters are moved from the input area to the output area in their sequential 
positions. You may specify the input area address as the output area address (R0 = Rl) when 
the $CVTUC routine is called. If you specify this at the outset. Register and Register 1 will 
be left pointing to the character following the string. The $CVTUC routine converts lowercase 
alphabetic characters to uppercase where they occur in the input area. The original lowercase 
contents of the input area are destroyed. 

$CVTUC destroys the contents of Register 2 and does not use Registers 3 through 5 of the 
calling task. 

Example 

The following source statements call the $CVTUC routine to convert an ASCII string to 
uppercase: 

MACNAM: 



BLKW 


3 


; WORK BUFFER 


MOV 


#MACNAM,R0 


; POINT TO WORK BUFFER 


MOV 


#6,R2 


; SAVE STRING COUNTER 


MOV 


R0.R1 


; POINT TO OUTPUT ADDRESS 


CALL 


$CVTUC 


; DO THE CONVERSION 



(In this example, the converted string will be stored in the buffer MACNAM because R0 = Rl.) 
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6.2 Date String Conversion Routine ($DAT) 

The $DAT routine converts the 3-word internal binary date to the standard 8- or 9-character 
ASCII output format. $DAT formats the date for output as follows: 

day-month-year 

Format 

CALL $DAT 

Input 

output address 

In Register 0: the address of the output area that will store the converted date 

input address 

In Register 1: the address of the 3-word input area that will store the binary date 

date values 

The input area must contain the following values: 
Word 1 = Last two digits of year 

Word 2 = A 2-digit number from 01 to 12 (month of year) 

Word 3 = A 2-digit number from 01 to 31 (day of month) 

Output 

date 

In the output area: the 8- or 9-character date string in the following format: 

dd-mmiii-yy 
dd Day (one character for 1 to 9 and two characters for 10 to 31) 
mmm Month (first three letters) 
yy Year (last two digits) 

next output address 

In Register 0: the address of the next available location in the output area 

next input address 

In Register 1: the next address (input Rl + 6) of the input area 

Description 

The $DAT routine uses and may destroy the contents of Register 2. The calling task should 
save any critical value contained in Register 2 before calling the $DAT routine. 

$DAT calls the $SAVRG routine to save and restore the contents of Registers 3 through 5 of 
the calling task. 
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Example 

The following source statements call the $DAT routine to convert the binary date stored in 
buffer DATBUF and store the formatted ASCII output in the buffer EDTBUF: 

DATBUF: .WORD 87. ; YEAR 

.WORD 11. ; MONTH 

.WORD 01. ! DAY 

EDTBUF: .BLKB 9. ; OUTPUT BUFFER 

.EVEN 

START: 

MOV #EDTBUF,R0 ; OUTPUT FROM CONVERSION 

MOV #DATBUF,R1 ; GET INPUT BUFFER 

CALL $DAT ; CONVERT DATE TO STANDARD ASCII FORMAT 

After execution, the output buffer will contain the following information: 

l-NOV-87 

6.3 Alternate Date String Conversion Routine ($DAT) 

The Alternate Date Routine ($DAT), accessed by the SYSLIB module INTDAS, converts the 
binary date in a format not dependent upon the DIGITAL-standard date format (dd-mmm-yy). 
The calling sequence is the same as for the standard format $DAT routine. 

Format 

CALL $DAT 

Input 

output address 

In Register 0: the address of the output area that will store the converted date 

input address 

In Register 1: the address of the 3-word input area that will store the binary date 

date values 

In the input area, the following definitions: 

Word 1 = Last two digits of year 

Word 2 = A 2-digit number from 01 to 12 (month of year) 

Word 3 = A 2-digit number from 01 to 31 (day of month) 

Output 

date 

In the output buffer: the converted and formatted string (up to 25 characters), determined 
by your definitions of the logical names SYS$DATE_FORMAT and SYS$MONTH_nn 

next output address 

In Register 0: the address of the next available location in the output area 
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next input address 

In Register 1: the next address (input Rl + 6) of the input area 

Description 

The alternate $DAT routine is contained in the module INTDAS, which has been inserted into 
SYSLIB with entry points deleted. To include the INTDAS module in your task image, you 
must explicitly request it in one of the following ways: 

• Before building the task, invoke the Librarian Utility (LBR) and enter the following command 
line to include the module INTDAS in the task: 

LB : [1 , 1] SYSLIB/LB : INTDAS 

• Insert the module EDDAT without entry points, and INTDAS with entry points, into SYSLIB 
by entering the following command sequence: 

>LBR 

LBR>EDDAT=LB : [1 , 1] SYSLIB . OLB/EX : EDDAT 

LBR>INTDAS=LB : [i , 1] SYSLIB . OLB/EX : INTDAS 

LBR>LB : [1 . 1] SYSLIB . OLB/RP/-EP=EDDAT 

LBR> LB :[!,! ] SYSLIB . OLB/RP=INTDAS 

LBR> |CTRL/Z| 

>PIP INTDAS. OBJ ;*/DE, EDDAT. OBJ;* 

The alternate $DAT routine's calling sequence remains the same as for the standard $DAT 
routine, but the logical name SYS$D ATE —FORMAT contains the following character formats: 

Argument Effect 

DD Print 2-digit day of month with leading zero 

ZD Print 2-digit day of month with leading zero suppressed 

MM Print 2-digit month number with leading zero 

ZM Print 2-digit month number with leading zero suppressed 

YY Print 2-digit year with leading zero 

ZY Print 2-digit year with leading zero suppressed 

MMM Print alphabetic month (not necessarily three characters long) 

You can use additional characters (other than the uppercase letters D, Z, M, and Y) in 
SYS$DATE_FORMAT as delimiters. If SYS$D ATE -FORMAT is not denned, you get the 
DIGITAL-standard date format (dd-mmm-yy) by default. SYS$D ATE -FORMAT can have a 
maximum length of 16 characters. 

The logical SYS$MONTH_nn (where nn is 01 to 12) provides the alphabetic month to be 
printed when the mmm attribute is used. If SYS$MONTH_ nn is not denned, you get the 
DIGITAL-standard 3-letter month abbreviations (mmm) by default. SYS$MONTH_nn can have 
a maximum length of 12 characters. 

Logical translation is done in standard order. A local terminal assignment can override a 
system-wide assignment, which permits the same program to produce output in the individual 
user's own language or preferred format. 
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There are two limitations to the alternate date routine. First, using it necessitates more output 
buffer space than the traditional format because the output produced can be as long as 25 
characters. The standard $DAT routine, however, produces eight or nine characters. Second, 
the new module can be linked with many, but not all, existing programs. An example of a 
program that cannot use this routine is one that performs operations on the resulting output 
string, expecting it to be in the format produced by the standard routine. 

The INTDAS module contains the routines $DAT and $TIM. The $TIM routine has not been 
modified; it produces the standard time format, as described in Section 6.4, Time Conversion 
Routine ($TIM). 

The $DAT routine uses and may destroy the contents of Register 2. The calling task should 
save any critical value contained in Register 2 before calling the $DAT routine. 

$DAT calls the $SAVRG routine to save and restore the contents of Registers 3 through 5 of 
the calling task. 

Examples 

Assume that you have replaced the SYSLIB module INTDAS into your library with entry points 
and are ready to run a program that calls the $DAT routine. Your definition, at the system 
prompt, of the logical names SYS$DATE_FORMAT and SYS$MONTH_nn will determine the 
output of the $DAT routine when it executes, as shown in the following examples: 

DEFINE SYS$DATE_FORMAT = "MMM ZD, 19YY" 
DEFINE SYS$MONTH_li = "November" 

Output: November 1,1987 

DEFINE SYS$DATE_FORMAT = "DD.MMM.YY" 
DEFINE SYS$M0NTH_11 = "XI" 

Output: 01. XI. 87 

SYS$DATE_FORMAT = "ZD/MM/YY" 

Output: 1/11/87 
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The $TIM routine converts the binary time, in a standard format, to an ASCII output string in 
the form: 

HH:MM:SS.S 

The $TIM routine converts and formats the time for output in one of the following forms: 

hour 

hour : minute 

hour : minute : second 

hour : minute : second . fraction 

Format 

CALL $TIM 
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Input 

The standard format for $TIM input values is shown in the following table: 



Word 


Significance 


Output 
Format 


Value Range 


WD1 


Hour-of-Day 


HH 


0to23 


WD2 


Minute-of-Hour 


MM 


0to59 


WD3 


Second-of-Minute 


SS 


to 59 


WD4 


Tick-of-Second 


.S 


Depends on clock frequency 


WD5 


Ticks-per-Second 


.S 


Depends on clock frequency 



output address 

In Register 0: the address of the output area that will store the converted time 

input address 

In Register 1: the starting address of the input area that stores the time values 

parameter count 

In Register 2, the parameter count, where: 

R2 = or 1, to specify that the hour (word 1) is to be converted in the format HH 

R2 = 2, to specify that the hour and minute (words 1 and 2) are to be converted in the 
format HH:MM 

R2 = 3, to specify that the hour, minute, and second (words 1, 2, and 3) are to be con- 
verted in the format HH:MM:SS 

R2 = 4 or 5, to specify that the hour, minute, second, and tick are to be converted in the 
format HH:MM:SS.S (where .S = tenth of second) 

Note 

For HH, the $TIM routine always returns two characters for all values 
specified. 

Output 

next output address 

In Register 0: the address of the next available location in the output area 

next Input address 

In Register 1: the address of the next word in the input area 

time string 

In the specified output area: the converted time string 
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Description 

The $TIM routine calls the $SAVRG routine to preserve Registers 3 through 5 of the calling 
task. The contents of Registers and 1 are updated and returned to the calling task. The $TIM 
routine destroys the contents of Register 2 (the parameter count). It also calls the following 
routines: 

• The $DIV routine, which performs the division required to convert binary values to ASCII 
format 

• The $CBDAT routine, which actually performs the time conversion, two digits at a time 
The $TIM routine does not check the validity of the input data. 

Example 

The following source statements call the $DAT and $TIM routines to convert time values to the 
standard formats: 

Assume a program contains an input block, an output block, and source statements. For 
example: 



BDBLK: .WORD 87. 

.WORD 11. 

.WORD 01. 

.WORD 10. 

.WORD 15. 

.WORD 35. 

.WORD xx 

.WORD x 

DTBLK: .BLKB 20. 

MOV #DTBLK,R0 

MOV #BDBLK,R1 

CALL $DAT 

MOVB #11,(R0)+ 



MOV #3.,R2 
CALL $TIM 



YEAR 

MONTH 

DAY 

HOUR 

MINUTES 

SECONDS 



PUTS ADDRESS OF OUTPUT AREA IN REGISTER 

PUTS ADDRESS OF INPUT BINARY DATE AREA IN REGISTER 1 

CALLS THE $DAT ROUTINE 

PUTS TAB AFTER DATE IN OUTPUT BUFFER 

REGISTER NOW CONTAINS NEXT ADDRESS IN DTBLK FROM $DAT 
REGISTER 1 NOW CONTAINS ADDRESS OF NEXT WORD (THE 
HOUR 10) IN BDBLK FROM $DAT 
SPECIFIES THE HH:MM:SS FORMAT FOR CONVERTED TIME 
CALLS THE $TIM ROUTINE 



After execution, the output buffer will contain the following information: 



1-N0V-87 



10:15:35 



The time and date fields are left-justified. 

6.5 Edit Message Routine ($EDMSG) 

The $EDMSG routine converts internally stored data to ASCII decimal, octal, or alphanumeric 
characters, and controls the layout of the converted characters. You can use the $EDMSG 
routine to produce printed or displayed text in meaningful, readable formats. 

Format 

CALL IEDMSG 
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Input 

output address 

In Register 0: the starting address of the output block 

input address 

In Register 1: the address of the input string 

argument block address 

In Register 2: the starting address of the argument block 

input string 

The input string contains the editing directives and ASCII text that determine data conversion 
and format control for the $EDMSG routine. The directives must be in one of the following 
formats: 

• %1 

• %nl 

• %V1 

The directives have the following effects: 

Directive Effect 

% A delimiter that identifies an editing directive to the $EDMSG routine. 

n An optional repeat count (decimal number) specifying the number of times 

the editing operation is to be repeated by the $EDMSG routine. If n = or 
is not specified, a repeat count of 1 is assumed. 

V Specifies that the repeat count is a value in the next word in the task's argu- 

ment block. If the value is 0, a repeat count of 1 is assumed. 

1 An alphabetic letter specifying one of the editing operations to be performed 

by the $EDMSG routine, as shown in Table 6-1. 

Input strings may contain ASCII text as well as editing directives. Any number of directives 
may appear in an input string. Input strings must be in ASCIZ format. 

argument block (ARGBLK) 

The argument block contains the binary data to be converted, the addresses of ASCII and 
extended ASCII characters, or the address of a double-precision value. 

Prior to calling the $EDMSG routine, set up the appropriate argument block, as follows: 

• For $EDMSG to move ASCII or extended ASCII characters to the output block, the 
argument block must contain the address of the ASCII characters. 

• For $EDMSG to convert a binary byte to octal format, the argument block must contain 
the address of the binary byte. 

• For $EDMSG to convert binary values, the argument block must contain the values. 
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• For $EDMSG to perform filename string conversion, the argument block must contain 
the following information: 

Word 1 = Radix-50 file name 

Word 2 = Radix-50 file name 

Word 3 = Radix-50 file name 

Word 4 = Radix-50 file type 

Word 5 = Binary version number 

• For $EDMSG to convert a binary date, the argument block must contain the following 
information: 

Word 1 = Year (last two digits) 

Word 2 = Number (01 to 12) of month 
Word 3 = Day of month (01 to 31) 

Note 

$EDMSG does not check the validity of the date values. If you specify 
erroneous date values, output results will be unpredictable. 

• For $EDMSG to convert binary time, the argument block must contain the following 
information: 

Word 1 = Hour-of-day (0 to 23) 

Word 2 = Minute-of-hour (0 to 59) 

Word 3 = Second-of-minute (0 to 59) 

Word 4 = Tick-of -second (depends on clock frequency) 

Word 5 = Ticks-per-second (depends on clock frequency) 

output block (OUTBLK) 

The output block in which $EDMSG is to store output 

Output 

converted data 

In the output block: the converted/formatted data 

next byte 

In Register 0: the address of the next available byte in the output block (the $EDMSG 
routine clears this byte to provide a null-terminated (ASCIZ) string) 

output length 

In Register 1: the number of bytes transferred to the output block (the count does not 
include the null-terminating byte) 

next argument address 

In Register 2: the address of the next argument in the argument block 
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Table 6-1 describes the editing directives for the $EDMSG routine. 



Table 6- 1 : $EDMSG Routine Editing Directives 



Directive 



Form Operation 



A (ASCII 1 string) 



B (binary byte to 
octal conversion) 



D (binary to signed 
decimal conversion, 
suppress) 



E (extended 
ASCII 1 ) 


%E 




%nE 




%VE 


F (form feed) 


%F 




%nF 




%VF 



%A Move the ASCII character from address in ARGBLK to OUTBLK. 

%nA Move the next n ASCII characters from address in ARGBLK to 
OUTBLK. 

%VA Use the value in the next word in ARGBLK as repeat count and 
move the specified number of ASCII characters from address in 
ARGBLK to OUTBLK. 

%B Convert the next binary byte from address in ARGBLK to unsigned 
octal number and store result in OUTBLK. 

%nB Convert the next n binary bytes from address in ARGBLK to oc- 
tal numbers and store results in OUTBLK; insert space between 
numbers. 

%VB Use the value in the next word in ARGBLK as the repeat count, 
convert the specified number of binary bytes from address in 
ARGBLK to octal numbers, and store results in OUTBLK; insert 
space between numbers. 

%D Convert the binary value in the next word in ARGBLK to signed 
decimal and store result in OUTBLK. 

%nD Convert the next n binary values in ARGBLK to signed decimal 
and store results in OUTBLK; insert tab between numbers. 

%VD Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of binary values to signed decimal, and 
store results in OUTBLK; insert tab between numbers. 

Move the extended ASCII character from the address in ARGBLK 
to the OUTBLK. 



Move n extended ASCII characters from the address in ARGBLK 
to OUTBLK. 

Use the value in the next word in ARGBLK as repeat count and 
move the specified number of ASCII characters from the address 
in ARGBLK to OUTBLK. 

Insert a form-feed character in OUTBLK. 

Insert n form-feed characters in OUTBLK. 

Use the value in the next word in ARGBLK as repeat count and 
insert specified number of form-feed characters in OUTBLK. 



1 Extended ASCII characters consist of the printable characters in the 7-bit ASCII code. If nonprintable characters appear in an 
ASCII input string, the E directive replaces them with a space, while the A directive transfers the nonprintable characters to the 
output block. 
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Table 6-1 (Cont.): $EDMSG Routine Editing Directives 



Directive 



Form Operation 



I (include ASCIZ 
string) 

M (binary to 
decimal magnitude 
conversion, 
suppress) 



N (new line- 
carriage return/ 
line feed) 



O (binary to 
signed octal 
conversion) 



P (binary to 
unsigned octal 
magnitude 
conversion, 
no suppress) 



%I Use the next value in ARGBLK as the address of an ASCIZ string 
to be logically included in the format string at this point. 

%M Convert the binary value in the next word in ARGBLK to decimal 
magnitude with leading zeros suppressed and store the result in 
OUTBLK. 

%nM Convert the next n binary values in ARGBLK to decimal magni- 
tude with leading zeros suppressed and store the results in 
OUTBLK; insert tab between numbers. 

%VM Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of binary values to decimal magnitude 
with leading zeros suppressed, and store the results in OUTBLK; 
insert tab between numbers. 

%N Insert CR and LF characters in OUTBLK. 

%nN Insert n CR and LF characters in OUTBLK. 

%VN Use the value in the next word in ARGBLK as repeat count and 
insert the specified number of CR and LF characters in OUTBLK. 

%0 Convert the binary value in the next word in ARGBLK to signed 
octal and store the result in OUTBLK. 

%nO Convert the next n binary values in ARGBLK to signed octal and 
store the results in OUTBLK; insert tab between numbers. 

%VO Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of binary values to signed octal, and 
store the results in OUTBLK; insert tab between numbers. 

%P Convert the binary value in the next word in ARGBLK to octal 
magnitude with no leading zeros suppressed and store the result 
in OUTBLK. 

%nP Convert the next n binary values in ARGBLK to octal magnitude 
with no leading zeros suppressed and store the results in OUTBLK; 
insert tab between numbers. 

%VP Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of binary values to octal magnitude with 
no leading zeros suppressed, and store the results in OUTBLK; 
insert tab between numbers. 
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Table 6-1 (Cont.): $EDMSG Routine Editing Directives 



Directive 



Form Operation 



Q (binary to 
octal 

magnitude 
conversion, 
suppress) 



%Q Convert the binary value in the next word in ARGBLK to octal 
magnitude with leading zeros suppressed and store the result in 
OUTBLK. 



%nQ 
%VQ 



R (Radix-50 
to ASCII) 


%R 




%nR 




%VR 


S (space) 


%S 




%nS 




%VS 


T (double- 
precision binary 
to decimal 
conversion) 


%T 
%nT 



U (binary to 
decimal magnitude 
conversion, 
no suppress) 



%VT 

%U 
%nU 



Convert the next n binary values in ARGBLK to octal magnitude 
with leading zeros suppressed and store the results in OUTBLK; 
insert tab between numbers. 

Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of binary values to octal magnitude with 
leading zeros suppressed, and store the results in OUTBLK; insert 
tab between numbers. 

Convert the Radix-50 value in the next word in ARGBLK to ASCII 
and store the result in OUTBLK. 

Convert the next n Radix-50 values in ARGBLK to ASCII and store 
the results in OUTBLK. 

Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of Radix-50 values to ASCII, and store 
the results in OUTBLK. 

Insert a space in OUTBLK. 

Insert n spaces in OUTBLK. 

Use the value in the next word in ARGBLK as repeat count and 
insert the specified number of spaces in OUTBLK. 

Convert the double-precision unsigned binary value at the address 
in ARGBLK to decimal and store result in OUTBLK. 

Convert the next n double-precision binary values starting at the 
address in ARGBLK to decimal and store results in OUTBLK; in- 
sert tab between numbers. 

Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of double-precision binary values start- 
ing at the address in ARGBLK to decimal, and store the results in 
OUTBLK; insert tab between numbers. 

Convert the binary value in ARGBLK to decimal magnitude with 
no leading zeros suppressed and store result in OUTBLK. 

Convert the next n binary values in ARGBLK to decimal magni- 
tude with no leading zeros suppressed and store results in 
OUTBLK; insert tab between numbers. 
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Table 6-1 (Cont.): SEDMSG Routine Editing Directives 



Directive 



Form Operation 



X (filename 
string conversion) 



Y (date 
conversion) 



Z (binary time 
conversion) 



< (define 
byte field) 

> (locate 
field mark) 



%VU Use the value in the next word in ARGBLK as repeat count, con- 
vert the specified number of binary values to decimal magnitude 
with no leading zeros suppressed and store results in OUTBLK; 
insert tab between numbers. 

%X Convert Radix-50 filename string in ARGBLK to ASCII string in 
format name.typ; convert octal version number, if present, to 
ASCII and store results in OUTBLK. 

%nX Convert next n Radix-50 filename strings in ARGBLK to ASCII 
strings in format name.typ; convert octal version numbers, if 
present, to ASCII and store results in OUTBLK; insert tab between 
strings. 

%VX Use the value in the next word in ARGBLK as repeat count, con- 
vert specified number of Radix-50 filename strings to ASCII strings 
in format name.typ; convert octal version numbers, if present, to 
ASCII and store results in OUTBLK; insert tab between strings. 

%Y Convert the next three binary words in ARGBLK to ASCII date 
in format dd-mmm-yy and store in OUTBLK. For this directive, a 
repeat is acceptable but will be ignored. 

%0Z Convert binary hour-of-day in the next word of ARGBLK to ASCII 

or and store in OUTBLK in format HH. 

%1Z 

Convert the binary hour-of-day and minute-of-hour in the next 
%2Z two words of ARGBLK to ASCII and store in OUTBLK in format 

HH:MM. 

%3Z Convert the binary hour-of-day, minute-of-hour, and second-of- 
minute in the next three words of ARGBLK to ASCII and store in 
OUTBLK in format HH:MM:SS. 

%4Z Convert the binary hour-of-day, minute-of-hour, second-of-minute, 
or and ticks-of-second or ticks-per-second in the next five words of 

%5Z ARGBLK to ASCII and store in OUTBLK in format HH:MM:SS.S, 
where .S = tenth of second. 

%n < Insert n ASCII spaces followed by a field mark (NUL) in OUTBLK 
to define a fixed-length byte field. The output pointer will point 
to the first space. 

%n> Increment the OUTBLK pointer until a field mark (NUL) is located 
or the n repeat count is exceeded. 



Description 

The $EDMSG routine converts internally formatted data, in an argument block, to external 
format and stores it in the calling task's output block. The editing performed by the $EDMSG 
routine is specified by user directives within an input string. Any nonediting directive characters 
are simply copied into the output block. Output strings are in ASCIZ format. 
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The $EDMSG routine calls the output data conversion routines described in Chapter 5 and in 
Section 6.2 of this chapter to convert binary data to the specified external format. See the 
detailed descriptions of individual conversion routines for specific output formats. 

The $EDMSG routine scans the input string, character-by-character. If it encounters nondirective 
(or "unknown" directive) characters, it transmits them directly to the task's output block. When 
the $EDMSG routine finds a percent sign ( % ) delimiter, it interprets the character(s) following 
the delimiter. If it encounters a data conversion directive, the $EDMSG routine accesses the 
argument block, converts the specified data, and transmits it to the output block. If a format 
control directive is encountered, the routine generates the specified control(s) and transmits the 
data to the output block. If the percent sign delimiter is not followed by a valid operator, 
or if multiple delimiters are found, the $EDMSG routine transmits the first delimiter (and any 
subsequent delimiters not followed by a valid directive character) to the output block. 

Note 

You can call an appropriate output routine to output the converted/formatted 
data. 

$EDMSG calls the $SAVRG routine to save and restore Registers 3 through 5 of the calling task. 

Examples 

1. The following source statements call the $EDMSG routine to format the data stored in 
ARGBLK, as specified by the directives in buffer ISTRING: 



ISTRING: 


.ASCIZ /%F%1 
.EVEN 


2S***1 


rEXT***X3N , /.8Sy.VDy.2N%12S***END 


ARGBLK: 


.WORD 3. 




NUMBER OF VALUES TO CONVERT 




.WORD 99. 




VALUES 




.WORD -37. 




TO 




.WORD 137. 




FORMAT 


OUTBLK: 


.BLKB 100. 




OUTPUT BLOCK 


START: 


MOV #0UTBLK. 


R0 


SET UP ADDRESS OF OUTPUT 




MOV #ISTRINC 


r.Rl 


SET UP ADDRESS OF INPUT 




MOV #ARGBLK, 


R2 


SET UP ARGUMENT BLOCK 




CALL $EDMSG 




DO THE FORMATTING 



The editing directives shown in this example have the following effects: 
Directive Effect 



%F 
%12S 

%3N 

%8S 

%VD 



Insert a form feed in OUTBLK (start a new page). 

Insert 12 spaces in OUTBLK and move the ASCII string to OUTBLK (indent 
the first line 12 spaces and insert the header ***TEXT***). 

Insert three pairs of CR-LF characters in OUTBLK (generate two blank lines). 

Insert eight spaces in OUTBLK (indent the next line eight spaces). 

Use the first value (3) in ARGBLK as the repeat count and convert the next 
three binary values in ARGBLK to signed decimal; store each value, followed 
by a tab, in OUTBLK (output three signed decimal numbers set up in columns). 
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Directive Effect 



%2N Insert two pairs of CR-LF characters in OUTBLK (generate one blank line). 

%12S Insert 12 spaces at the beginning of a line in OUTBLK and move the ASCII 
string to OUTBLK (indent 12 spaces and insert the text **«END*»**). 



The example will produce the following output: 

***TEXT*** 

99 -37 137 
***END**** 
The following example calls the $EDMSG routine to convert the data stored in IBLK, as 
specified by the formatting directives in the buffer INSTR: 



INSTR: 
IBLK: 



.ASCIZ /%F%5S***F. TREVISANI WORK REPORT FROM %Y TO XY***/ 
.EVEN 



PRBLK : 
BEGIN: 



.WORD 87. 
.WORD 8. 
.WORD 22. 
.WORD 87. 
.WORD 9. 
.WORD 16. 

.BLKB 100. 

MOV #PRBLK.R0 
MOV #INSTR,R1 
MOV #IBLK,R2 
CALL $EDMSG 



YEAR 

8TH MONTH (AUG) 

DAY 

YEAR 

9TH MONTH (SEP) 

DAY 

OUTPUT BLOCK 

SET UP ADDRESS OF OUTPUT 
SET UP ADDRESS OF INPUT 
SET UP ARGUMENT BLOCK 
DO THE CONVERSION 



The editing directives in the example have the following effects: 



Directive Effect 



%F Insert a form feed in PRBLK (start a new page). 

%5S Insert five spaces in PRBLK and move ASCII string to PRBLK (indent the line 

five spaces and output the header ***F. TREVISANI WORK REPORT FROM ). 

%Y Convert the next three words in IBLK to formatted date and store in PRBLK 

followed by ASCII text (insert 22-AUG-87 TO in header line). 

%Y Convert next three words in IBLK to formatted date and store in PRBLK fol- 
lowed by ASCII text (insert 16-SEP-87*** in header line). 



The above example will produce the following output: 
***F. TREVISANI WORK REPORT FROM 22-AUG-87 TO 16-SEP-87*** 
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Chapter 7 

Dynamic Memory Management Routines 



The dynamic memory management routines allow you to manually manage the space in a task's 
free dynamic memory. The free dynamic memory consists of all memory extending from the 
assembled code of the task to the highest virtual address owned by the task, excluding resident 
libraries. 

Initially, these routines allocate free dynamic memory as one large block, from the highest 
available memory address downward. Subsequent memory block allocations are made within 
the available memory blocks. Available memory blocks are maintained as a linked list of blocks 
in ascending order, pointed to by a 2-word listhead. Each free memory block contains a 2-word 
control field, where: 

• The first word contains the address of the next available block, or if there is not another 
block 

• The second word contains the size of the current block 

Memory allocation is either on a first-fit or best-fit basis. Allocation is always made from the 
top of the selected available dynamic memory block. The second word of the block is adjusted 
to reflect the new size of the current block of available dynamic memory. As memory blocks 
are allocated completely, they are removed from the free memory list. 

When memory blocks are deallocated (released), they are returned to the free memory list. The 
released memory blocks are relinked to the free memory list in ascending address order. If 
possible, released memory blocks are merged with adjacent memory blocks to form a single, 
large block of free dynamic memory. 

The following three routines perform dynamic memory management functions: 

• Initialize Dynamic Memory Routine ($INIDM), which initializes the task's free dynamic 
memory 

• Request Core Block Routine ($RQCB), which allocates blocks of memory in the free dynamic 
memory 

• Release Core Block Routine ($RLCB), which releases (deallocates) previously allocated 
memory blocks in the executing task's free dynamic memory 
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To use the dynamic memory management routines, provide the following information in the 
source program: 

• A 2-word free memory listhead in the following format: 

FREEHD: .BLKW 2 

• The appropriate call and argument(s) for the given routine, as described in Sections 7.1, 7.2, 
and 7.3. 

Before building the task, invoke the Librarian Utility (LBR) and enter the following command 
line to include the modules INIDM and EXTSK in the task: 

LB : [1 , 1]VMLIB/LB : INIDM: EXTSK 

7.1 Initialize Dynamic Memory Routine ($INIDM) 

The $INIDM routine establishes the initial state of the free dynamic memory available to the 
executing task. The free dynamic memory consists of all memory extending from the end of 
the task code to the highest virtual address used by the task, excluding resident libraries. 

Format 

CALL $INIDM 

Input 

free memory listhead 

In the program's data section: a 2-word memory listhead 

free memory listhead address 

In Register 0: the address of the free memory listhead 

Output 

first address 

In Register 0: the first address in the task 

last address 

In Register 1: the address following the task image (last available address in the free 
dynamic memory) 

memory size 

In Register 2: the size of the free dynamic memory 

Description 

The $INIDM routine performs the following actions: 

• Rounds the free dynamic memory base address to the next 4-byte boundary 

• Initializes the free dynamic memory as a single large block of memory 
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• Computes the total size of the free dynamic memory 

• Sets the outputs in Registers and 1 and returns to the calling task 
Registers 3 through 5 are not used. 

After initializing dynamic memory, your task may call the Request Core Block Routine ($RQCB) 
to allocate memory blocks in the dynamic memory and the Release Core Block Routine ($RLCB) 
to release the allocated blocks. 

Example 

The following source statements call the $INIDM routine to initialize a block of free dynamic 
memory and save the first address of the task in Register 0: 

SFREEHD:: .BLKW 2 ; FREE MEMORY LISTHEAD 



MOV #$FREEHD,RQ ; SET ARG FOR FREE MEM HEAD 
CALL $INIDM ; INITIALIZE MEMORY 

7.2 Request Core Block Routine ($RQCB) 

The $RQCB system library routine determines whether there is enough space available in the 
free dynamic memory to satisfy an executing task's memory allocation request. If memory is 
available, the $RQCB routine allocates the requested memory block. 

Format 

CALL $RQCB 

Input 

free memory listhead address 

In Register 0: the address of the free memory listhead 

block size 

In Register 1: the size (number of bytes) of the memory block to be allocated, where: 
Rl = A value greater than or equal to 0, to specify best-fit allocation 

Rl = A value less than 0, to specify first-fit allocation (the value is negated to determine 
block size) 

Output 

block address 

In Register 0: the dynamic memory address of the allocated block 

block size 

In Register 1: the actual size of the allocated block (requested size rounded to next 2-word 
boundary) 
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Condition Code 

C bit = Clear if allocation is successful 

C bit = Set if allocation is not successful 
The $RQCB routine calls the $SAVRG routine to save and restore Registers 3 through 5 of the 
calling task. Register 2 is destroyed. 

Example 

The following source statements call the $RQCB routine to allocate a block of dynamic memory 
and store the memory address in Register 0: 

$FREEHD: : .BLKW 2 ; FREE MEMORY LISTHEAD 



MOV #$FREEHD,R0 

MOV #512., Rl 

NEG Rl 

CALL $RQCB 



GET ADDRESS OF FREE CORE POOL 
SIZE OF BLOCK TO BE ALLOCATED 
NEGATE TO SPECIFY FIRST FIT 
REQUEST CORE BLOCK 



7.3 Release Core Block Routine ($RLCB) 

The $RLCB system library routine releases a block of previously allocated dynamic memory to 
the free memory list. The memory addresses determine the order of the memory list. 

Format 

CALL $RLCB 

Input 

free memory listhead address 

In Register 0: the address of the free memory listhead 

block size 

In Register 1: the size (number of bytes) of the block to be released 

output address 

In Register 2: the memory address of the block to be released 

Output 

released block 

In the free memory list: the released dynamic memory block 
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Description 

The $RLCB routine searches the free memory list until it finds the proper address slot and then 
merges the released block into the list. If possible, the released memory block is merged with 
adjacent blocks already in the free memory list. 

The $RLCB routine calls the $SAVRG routine to save and subsequently restore Registers 3 
through 5 of the calling task. Register is unchanged, while the contents of Registers 1 and 2 
are destroyed. 

Example 

The following source statements call the $RLCB routine to release a block of memory, stored in 
buffer FREEHD, to the free memory listhead: 



FREEHD: 


:.BLKW 


2 


FREE MEMORY LISTHEAD 


REFHD: 


.WORD 





REFERENCE LISTHEAD 




MOV 


REFHD, R2 


GET ADDRESS OF ENTRY 




MOV 


#4.R1 


GET SIZE OF ENTRY 




MOV 


#FREEHD.RO 


SET ADDRESS OF LISTHEAD 




CALL 


$RLCB 


RELEASE CORE BLOCK 
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Chapter 8 

Virtual Memory Management Routines 



The virtual memory management routines perform memory allocation and deallocation by 
paging to and from disk file storage to accommodate tasks that require more memory than that 
available in the task's free dynamic memory at any given time. That is, the routines allow you 
to bring pages into memory when they are needed, hold them there until they are no longer 
needed, swap the pages out, and reallocate their memory space to other pages. These routines 
do not require the memory management hardware and are not related to memory management 
directives. 

The virtual memory management routines perform the following major functions: 

• Virtual memory initialization 

• Dynamic memory allocation 

• Virtual memory allocation 

• Page management 

Although you can call the individual virtual memory management routines, it is more efficient 
to use them as automatic control systems by calling only the following key routines: 

• The Initialize Virtual Memory Routine ($INIVM), which initializes the task's dynamic 
memory and the disk work file 

• The virtual memory allocation routines Allocate Virtual Memory Routine ($ALVRT) and 
Allocate Small Virtual Block Routine ($ALSVB), which manage the allocation of large and 
small page blocks to enable page swapping to and from dynamic memory 

• The following page management routines: 

— The Convert and Lock Page Routine ($CVLOK), which converts a virtual address to a 
dynamic memory address and sets a lock byte in the memory page to prevent its being 
swapped out of memory until it is no longer needed 

— The Unlock Page Routine ($UNLPG), which clears the lock byte in a memory-resident 
page so that it can be released and its memory space reallocated to another page 

— The Convert Virtual to Real Address Routine ($CVRL), which converts a virtual address 
to a dynamic memory address 
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— The Write-Marked Page Routine ($WRMPG), which sets the "written into" flag of 
memory pages 

8. 1 Using the Virtual Memory Management Routines 

To call the virtual memory management routines, provide the appropriate call arguments and 
statements in the source program, as described in Sections 8.2 through 8.5 of this chapter. 

Your task should contain an error-handling routine and symbolic error codes, as described in 
Section 8.1.1. 

At task-build time, specify the file and the virtual memory management modules required by 
the task, as described in Section 8.1.2. 

8.1.1 User Error-Handling Requirements 

Four virtual memory management routines detect fatal error conditions. These routines require a 
user-written error-handling routine, entitled $ERMSG. In conjunction with the $ERMSG routine, 
you should include definitions of three global error codes and one global severity code in the 
task. The symbolic error codes are as follows: 



Global Error 



E$R4 Used by the $ALBLK routine when there is no dynamic memory available for 

allocation 

E$R73 Used by the $RDPAG and $WRPAG routines when a work file I/O error occurs 
during an attempt to swap pages between resident memory and disk storage 

E$R76 Used by the $ALVRT routine when there is no virtual storage available for 
allocation 

S$V2 (Severity code) Used by the four routines cited above to denote a fatal error that 

must be corrected before task execution can resume 

When a fatal error occurs, the detecting routine sets up the following input arguments: 

Register 1 = Low byte: error code 

High byte: severity code (always S$V2) 

Register 2 = Argument block address 

and issues the following call: 

CALL $ERMSG 

Note that most of the virtual memory management routines interact, directly or indirectly, with 
one of the four routines that call $ERMSG (see the General Block Diagram for each routine). 
The only exceptions, which do not result in a call to $ERMSG, are the following routines: 

$EXTSK 

$FNDPG 

$WRMPG 

$LCKPG 

$UNLPG 
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These five routines indicate error conditions by setting the Condition Code C bit. Your error- 
handling operations for these routines should respond to the Condition Code C bit. However, 
these routines may need to link with the error routine $ERMSG. Therefore, you must define 
the global symbols and an $ERMSG routine in your task whenever you use a virtual memory 
management routine. If you have not defined the error-handling routine within the task, the 
undefined global symbol diagnostic message will be generated at task-build time. 

A typical error-handling routine would print a message to indicate the specific error condition, 
close all files (including the work file), and exit. 



Example 

The following source statements illustrate a user-written error-handling routine that can be 
called by a virtual memory management routine: 



ER60: 
ER61: 
FILOPN : 

GENFLG: 
; 1 
; 2 

$ERMSG: 



ERM2: 



ERM3: 



.ASCIZ <15>/ACNT— Workfile - dynamic memory exhausted/ 

.ASCIZ <15>/ACNT —Workfile - 10 error or ADDR past EOF/ 

.BYTE ; FILE OPEN FLAG. = NO, 1 = YES 

.EVEN 

.WORD ; GENERAL FLAG WORD 

BIT - VIRTUAL FILE OPEN. 1 = OPEN, = CLOSED 

BIT 1 - ALLOCATE VIRTUAL BLOCK ERROR FLAG, 1 = ERROR 



BIS 

CMPB 

BNE 

MOV 

BR 

CMPB 

BNE 

MOV 

BR 



#2, GENFLG 

#E$R4,R1 

ERM2 

#ER6O,R0 

ERROR 

#E$R73,R1 

ERM3 

#ER61,R0 

ERROR 



; SET ALLOCATE BLOCK ERROR 
; DYNAMIC MEMORY ERROR? 
; NO 
; YES. GET MESSAGE 

; I/O ERROR OR ADDRESS PAST EOF? 

; NO 

; YES. GET MESSAGE 

; ERROR-HANDLING ROUTINE 



EXIT: TSTB FILOPN 

BLE 10$ 

CALL CLOSE 

10$: BIT #1, GENFLG 

BEQ 15$ 

CALL CLOSEV 



IS ACCOUNT FILE OPEN? 

NO 

ROUTINE TO CLOSE ACCOUNT FILE 

WORK FILE OPEN? 

NO 

ROUTINE TO CLOSE VIRTUAL FILE 



15$: 

ERROR: ; ERROR MESSAGE OUTPUT ROUTINE 

Note 

Generally, the error-handling routine should not attempt to return to the virtual 
memory management routine that detected the fatal error because no meaningful 
output would result. 
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8.1.2 Task-Buiiding Requirements 

There are two versions of the virtual memory management routines: the statistical version 
and the nonstatistical version. Each version consists of 12 program modules, each containing 
one or more routines, and a data storage module. Individual routines in the virtual memory 
management routines library may reference other routines. The relationship of the modules and 
routines in the library is shown in Table 8-1. 

Table 8- 1 : Contents ot the Virtual Memory Management Library File 



Module Name 
Statistical Nonstatistical 



Name of 
Routine(s) 



Routines Referenced 



ALBLK 


ALBLK 


ALSVB 


ALSVB 


CVRS 


CVRL 


EXTSK 


EXTSK 


FNDPG 


FNDPG 


GTCOS 


GTCOR 


INIDM 2 


INIDM 2 


INIVS 


INIVM 


MRKPG 


MRKPG 



RDPAS 

RQVCB 

VMUTL 
VMDAS 



RDPAG 

RQVCB 
VMUTL 
VMDAT 



$ALBLK SGTCOR, $EXTSK, $WRPAG 

$ALSVB $ALVRT, $WRMPG, $CVRL, $ALBLK, $RQVCB, 
$FNDPG, $RDPAG 

$CVRL $FNDPG, $ALBLK, $RDPAG 

$EXTSK (none) 

$FNDPG (none) 

$GTCOR SEXTSK, 1 $WRPAG 

$INIDM $EXTSK 

$INIVM $ALBLK, SGTCOR, $EXTSK, $WRPAG 

$LCKPG $FNDPG 

$UNLPG $FNDPG 

$WRMPG $FNDPG 

$RDPAG (none) 
$WRPAG 

$RQVCB (none) 

$CVLOK $CVRL, $LCKPG, $FNDPG, $ALBLK, $RDPAG 

Global data storage module 



'"The Extend Task Routine (SEXTSK) is called by the $GTCOR routine, but only if GTCOS, the statistical version of $GTCOR, has 
been defined and initialized in your source program at task-build time. (See Section 8.3 and Figure 8-4.) 

The INIDM module is a dynamic memory management module (see Chapter 7) that is normally used with the virtual memory 
management routines. 

Four modules in the statistical version of the routines set up or maintain statistics of the use 
of the work file and memory. These modules and their associated statistical data fields are as 
follows: 

• The INIVS module, which initializes the following three double-word fields: 

— The total work file access field ($WRKAC) 

— The work file read count field ($WRKRD) 
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— The work file write count field ($WRKWR) 

Each of these fields is a double-word integer contained in the global data storage module 
(VMDAS) for the statistical version of the routines. 

• The CVRS module, which maintains the count of total work file accesses in the $WRKAC 
field. 

• The RDPAS module, which maintains a total of the work file reads in the $WRKRD field 
and a total of the work file writes in the $WRKWR field. 

• The GTCOS module, which maintains a count of the total amount of free dynamic memory 
in the $FRSIZ single-word field. This field must be defined and initialized in the source 
program. 

The statistical version of the virtual memory management routines does not automatically report 
these statistics. It is your responsibility to provide for the output of the statistical data in the 
fields described above if the statistical version of the routines is used. 

To use the statistical routines, specify at task-build time the virtual memory management routines 
library file, the names of all statistical modules whose routines will be used at task-execution 
time, and the name of the global data storage module. The only optional modules are ALSVB 
and INIDM. 

The following specifications identify all modules of the statistical version of the routines: 

LB : [1 , 1] VMLIB/LB : ALBLK : ALSVB : ALVRT : CVRS : EXTSK : FNDPG : GTCOS 
LB :[ 1 , 1] VMLIB/LB : INIVS : MRKPG : RDPAS : RQVCB : VMUTL : INIDM : VMDAS 

The nonstatistical routines use the global data storage module VMDAT. To use the nonstatistical 
routines, you specify at task-build time the virtual memory management routines library file, the 
names of all nonstatistical modules whose routines will be used at task-execution time, and the 
name of the global data storage module. The only optional modules are ALSVB and INIDM. 

The following specifications identify all modules of the nonstatistical version of the routines: 
LB : [1 . 1] VMLIB/LB : ALBLK : ALSVB : ALVRT : CVRL : EXTSK : FNDPG : GTCOR 
LB : [1 , 1] VMLIB/LB : INIVM : MRKPG :RDP AG :RQVCB : VMUTL : INIDM : VMDAT 

8.2 Virtual Memory Initialization Routine ($INIVM) 

The $INIVM routine initializes the task's free dynamic memory, sets up the page address control 
list, and initializes your disk work file to enable memory-to-disk page swapping. Disk work file 
capacity is 64K words. 

Format 

CALL $INIVM 
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Input 

$FRHD block 

In your source program: define and initialize a 2-word held named $FRHD. To define the 
field, include the following code in your source program: 

$FRHD:: .BLKW 2. 
To initialize the field, store the starting address of the free dynamic memory in $FRHD. 

globals 

In your source program: four global symbols as follows: 

W$KLUN Logical unit number (LUN) to be used for the work file. You must assign this 
LUN to a disk device. 

W$KEXT Work file extension size (in blocks). A negative number indicates that the ex- 
tend should first be requested as a contiguous allocation of disk blocks. A pos- 
itive number indicates that the extend need not be contiguous. 

N$MPAG Fast page search page count. If there is sufficient dynamic memory to allocate 
the number of pages specified, N$MPAG will set aside 512 words of dynamic 
memory to speed up the searching of memory-resident pages. 

$WRKPT Store the address of the FDB in the word $WRKPT before calling $INIVM. 

memory address 

In Register 1: the highest address of the task's free dynamic memory 

Output 
Condition Code 

Initialization succeeded if both of the following conditions exist: 

C bit = Clear 

Register 0=0 

Initialization failed if the following conditions exist: 

C bit = Set 

Register = One of the following values: 

-2 to indicate work file open failure 

-1 to indicate work file mark-for-deletion failure 

Note 
Before calling the $INIVM routine, the task may call the $INIDM routine (see 
Chapter 7), which returns the last address of dynamic memory and the total 
size of dynamic memory. 

Also, you can examine the FCS error code at offset F.ERR in the work file FDB. 
The address of the FDB is stored in the word $WRKPT. 
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Description 

Starting at the high address of the calling task's free dynamic memory, the $INIVM routine 
clears control fields and the page address control listhead. The $INIVM routine then sets up 
the heading for a new page address control list and calls the Allocate Block Routine ($ALBLK) 
to allocate a memory page block for the control list. The $INIVM routine calls the $ALBLK 
routine to allocate a page block for the first memory page for the calling task, and links the first 
allocated page to the page control list. 

The $INIVM routine initializes (opens) your disk work file. If the file is opened successfully, 
the $IMVM routine attempts to mark it for deletion. This ensures that the file will be deleted 
automatically when it is closed, or if the task terminates abnormally or exits. 

Note 
The work file may be closed by the operation CLOSES $WRKPT. 

The $INIVM routine destroys the contents of Registers through 2. Whether or not the 
initialization is successful, it transfers control to the $SAVRG routine, which restores Registers 
3 through 5 and returns to the calling task. 

The interaction of the $INIVM routine with your task and the Allocate Block Routine ($ALBLK) 
is shown in Figure 8-1 (see next page). 
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Figure 8-1: General Block Diagram of the $INIVM Routine 
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Example 

The following source statements call the $INIVM routine to initialize free dynamic memory and 
then call $WRKPT to close the work file. In this example, the $INIDM routine provides the 
required free memory address in Register 1: 



E$R4 


== 


4 


INSUFFICIENT WORK FILE DYNAMIC MEMORY 


ESR73 


== 


73 


WORK FILE I/O ERROR 


E$R76 


== 


76 


WORK FILE EXCEEDED 


S$V2 


== 


302 


SEVERITY 2 


W$KLUN 


== 


4 


WORK FILE LUN 


N$MPAG 


== 


20 


FAST PAGE SEARCH PAGE COUNT 


W$KEXT 


== 


24 


WORK FILE EXTENSION SIZE (BLOCKS) 


$WRKPT 


.WORD 





ADDRESS OF FDB 


SFRHD: 


.BLKW 


2 


FREE MEMORY LISTHEAD 


$FRSIZ 


: .BLKW 


1 


SIZE COUNT FOR FREE MEMORY 


GENFLG 


-WORD 





GENERAL WORD FLAG 




; 1 


BIT - VIRTUAL FILE OPEN - 1 = OPEN, = CLOSED 




MOV 


#$FRHD,RO 


SET ARG FOR FREE MEMORY HEAD 




CALL 


SINIDM 


INITIALIZE MEMORY 




MOV 


R2.JFRSIZ 


SET ARG FOR SIZE 




CALL 


$INIVM 


INITIALIZE WORK FILE SUBSYSTEM 




CLOSES $WRKPT ; 


CLOSE VIRTUAL WORK FILE 




BIC 


#1. GENFLG ; 


CLEAR WORK FILE OPEN FLAG 




RTS 


PC 





8.3 Core Allocation Routines 

The core allocation routines manage the allocation and deallocation of space in the free dynamic 
memory of the executing task. The core allocation routines are as follows: 

• The Allocate Block Routine ($ALBLK), which provides the interface between the executing 
task and the other core allocation routines. That is, the executing task is provided all the 
services of the core allocation routines by simply calling the $ALBLK routine, or those 
routines that call the $ALBLK routine. 

• The Get Core Routine ($GTCOR), which is always called by the $ALBLK routine to perform 
the necessary processing to allocate the requested memory space from the free dynamic 
memory. 

• The Request Core Block Routine ($RQCB), which is called by the $GTCOR routine to 
allocate the requested memory space if it is available in the free dynamic memory. 

• The Write Page Routine ($WRPAG), which is called by the $GTCOR routine to transfer 
memory pages to your disk work file to free enough memory space to satisfy the memory 
allocation request. 

• The Release Core Block Routine ($RLCB), which is called by the $GTCOR routine to release 
space previously allocated to a memory page that has been transferred to the disk work file. 
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In addition to the five core allocation routines mentioned above, there is a sixth routine called 
the Extend Task Routine ($EXTSK), which is accessed by the statistical module GTCOS. The 
$EXTSK routine is called by the $GTCOR routine to extend the size of the task region, thus 
making enough memory available in the free dynamic memory to satisfy the allocation request. 

Do not confuse the statistical module GTCOS with the nonstatistical module GTCOR. Both of 
these modules are called by references to the entry point $GTCOR. $GTCOR calls $EXTSK 
only when you include the statistical module GTCOS at task-build time. If you do not include 
GTCOS, the $GTCOR routine uses the nonstatistical module GTCOR by default. 

8.3.1 Allocate Block Routine ($ALBLK) 

The $ALBLK routine determines whether a block of memory storage can be allocated from the 
free dynamic memory. If so, the $ALBLK routine clears (zeroes) the allocated block and returns 
the resident memory address of the block to the calling task. If there is insufficient space in the 
free dynamic memory, the requested block cannot be allocated. 

Format 

CALL $ALBLK 

Input 

block size 

In Register 1: the size (number of bytes less than or equal to 512i ) of the memory storage 
block to be allocated 

error code 

In the task: the definitions for the following global symbols: 

E$R4 
S$V2 

Output 

block address 

In Register 0: the dynamic memory address of the allocated, cleared block 

error response 

If allocation is unsuccessful, $ALBLK produces the following output: 
In Register 1: sets the error/severity codes E$R4 and S$V2 
In Register 2: saves the address of the argument block $FRHD (free memory header) 

The $ALBLK routine then calls the user $ERMSG routine. 

Description 

The $ALBLK routine calls the Get Core Routine ($GTCOR) to allocate the requested memory 
block, as follows: 

• Request allocation from the free dynamic memory 

• If the request is not met, attempt to extend the task region to increase the size of the free 
dynamic memory 
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• If the task cannot be extended, swap unlocked pages from memory storage to disk to 
deallocate memory space for reallocation 

In addition to being called by the user task, the $ALBLK routine is called by the following 
virtual memory management routines: 

• Initialize Virtual Memory Routine ($INIVM), which calls $ALBLK to allocate initial blocks 
of dynamic memory to enable page swapping between disk and memory storage 

• Convert Virtual to Real Address Routine ($CVRL), which calls $ALBLK to allocate a block 
of dynamic memory for a virtual page block 

• Allocate Virtual Memory Routine ($ALVRT), which calls $ALBLK to allocate a memory page 
block for a virtual page block that is to be swapped from memory to disk storage 

The interaction of the $ALBLK routine with a user task and other virtual memory management 
routines is shown in Figure 8-2. 

Figure 8-2: General Block Diagram of the $ALBLK Routine 
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E$R4 


== 


4 


E$R73 


== 


73 


E$R76 


== 


76 


S$V2 


= 


2 


REFHD: 


BLKW 


2 




MOV 


Rl.-(SP) 




MOV 


#4,R1 




CALL 


$ALBLK 




MOV 


RO , CREFHD+2 




MOV 


RO.REFHD+2 




MOV 


(SP)+.2(R0) 



Example 

The following source statements call the $ALBLK routine to allocate a 4-byte block of memory 
and store the address of the block in buffer REFHD: 

INSUFFICIENT WORK FILE DYNAMIC MEMORY 
WORK FILE I/O ERROR 
WORK FILE EXCEEDED 
SEVERITY 2 
REFERENCE LISTHEAD 

SAVE VIRTUAL ADDRESS OF REFERENCE 

GET SIZE OF BLOCK 

ALLOCATE CORE BLOCK 

LINK REAL ADDRESS TO OLD LAST BLOCK ADDRESS 

SET NEW LAST BLOCK ADDRESS 

RECORD VIRTUAL ADDRESS OF REFERENCE 

8.3.2 Get Core Routine ($GTCOR — Nonstatistical Module GTCOR) 

The SGTCOR routine (defined in the nonstatistical module GTCOR) attempts to allocate 
requested dynamic memory blocks in the following ways: 

• Allocate memory from the currendy available space in the free dynamic memory 

• Swap unlocked page blocks from dynamic memory to disk, freeing previously allocated 
memory space for reallocation 

Format 

CALL SGTCOR 

Input 

block size 

In Register 1: the size (number of bytes less than or equal to 512 10 ) of the dynamic memory 
block to be allocated 

Output 

block address 

In Register 0: the memory address of the dynamic memory block, if allocated 

Condition Code 

C bit = Clear if the allocation was successful 

C bit = Set if the allocation failed 

Description 

SGTCOR calls the Request Core Block Routine ($RQCB; described in Chapter 7) to determine 
whether enough free dynamic memory space is currently available to satisfy the allocation 
request. If so, the $GTCOR routine returns the memory address of the resident block to the 
caller. 
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If the $RQCB routine cannot allocate the requested block from the current free dynamic memory, 
the $GTCOR routine searches for the unlocked pages currently resident in memory. If any 
unlocked pages are found, the least recently used (LRU) page is released and its memory space 
is allocated to the new page. If an unlocked page cannot be found, $GTCOR sets the C bit, 
indicating that it failed to find an unlocked page, and returns control to the caller. 

When an LRU page is found, the $GTCOR routine checks the page to see if it has been written 
into. If so, the Write Page Routine ($WRPAG) is called to write the page to the disk work 
file. The Release Core Block Routine ($RLCB; described in Chapter 7) is called to release the 
page and the Request Core Block Routine ($RQCB) is called to allocate the page. The memory 
address of the allocated page returns in Register to the caller. If the $GTCOR routine does not 
obtain sufficient memory for the requested block, it sets the C bit in the Condition Code and 
returns control to the caller. $GTCOR calls the $SAVRG routine to save and restore Registers 
3 through 5 of the caller. 

The $GTCOR routine is always called by the Allocate Block Routine ($ALBLK). 

The interaction of the $GTCOR routine with other system library and virtual memory 
management routines is shown in Figure 8-3 (see next page). 
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Figure 8-3: General Block Diagram of the $GTCOR Routine (nonstatistical module 
GTCOR) 
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Example 

The following source statements call the $GTCOR routine to allocate a memory block of one 
byte plus the length of the header: 



E$R4 


== 


4 


INSUFFICIENT WORK FILE DYNAMIC MEMORY 


E$R73 


== 


73 


WORK FILE I/O ERROR 


E$R76 


== 


76 


WORK FILE EXCEEDED 


S$V2 


== 


302 


SEVERITY 2 


LENGTH: 


.BLKW 


1 


LENGTH OF RECORD JUST READ 


HDSZ: 


.BLKW 
.EVEN 


1 


LENGTH OF HEADER 




MOV 


#1,R0 


SET LENGTH TO ONE BYTE 




MOV 


RO, LENGTH 


REMEMBER THE LENGTH 




ADD 


#HDSZ,R1 


ADD HEADER LENGTH 




ADD 


R0.R1 


ADD ALLOWANCE FOR MODIFICATIONS 




CALL 


$GTC0R 


ALLOCATE SPACE 



8.3.3 Get Core Routine ($GTCOR— Statistical Module GTCOS) 

The $GTCOR routine (accessed by the statistical module GTCOS) attempts to allocate requested 
dynamic memory blocks in one of the following ways: 

• Allocate memory from the currently available space in the free dynamic memory 

• Extend the task region, increasing the size of the free dynamic memory to accommodate 
the allocation request 

• Swap unlocked page blocks from dynamic memory to disk, which frees previously allocated 
memory space for reallocation 

Format 

CALL $GTC0R 

Input 

block size 

In Register 1: the size (number of bytes less than or equal to 512i ) of the dynamic block 
memory to be allocated 

Output 

address 

In Register 0: the memory address of the dynamic block, if allocated 

Condition Code 

C bit = Clear if the allocation was successful 

C bit = Set if the allocation failed 
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Description 

The Request Core Block Routine ($RQCB; described in Chapter 7) is called to determine whether 
enough free dynamic memory space is currently available to satisfy the allocation request. If 
so, the $GTCOR routine returns the memory address of the resident block to the caller. 

If the requested block cannot be allocated from the current free dynamic memory, the $GTCOR 
routine calls the Extend Task Routine ($EXTSK) to determine whether the task region can be 
extended to make available the requested space in the free dynamic memory. If so, the $GTCOR 
routine returns the memory address to the caller. 

If the task region cannot be extended, the $GTCOR routine searches for unlocked pages currently 
resident in memory. If any unlocked pages are found, the least recently used (LRU) page is 
released and its memory space is allocated to the new page. 

When an LRU page is found, the $GTCOR routine checks the page to see if it has been written 
into. If so, the Write Page Routine ($WRPAG) is called to write the page to the disk work 
file. The Release Core Block Routine ($RLCB; described in Chapter 7) is called to release the 
page and the Request Core Block Routine ($RQCB) is called to allocate the page. The memory 
address of the allocated page is returned in Register to the caller. If the $GTCOR routine is 
not able to obtain sufficient memory for the requested block, it sets the C bit in the Condition 
Code and returns control to the caller. The $GTCOR routine calls the $SAVRG routine to save 
and subsequently restore Registers 3 through 5 of the caller. 

The $GTCOR routine is always called by the Allocate Block Routine ($ALBLK). 

The interaction of the $GTCOR routine with other system library and virtual memory 
management routines is shown in Figure 8-4. 
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Figure 8-4: General Block Diagram of the $GTCOR Routine (statistical module 
GTCOS) 
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8.3.4 Extend Task Routine ($EXTSK) 

The $EXTSK routine extends the current region of the task to increase the amount of available 
memory for allocation. It extends the task region by the specified size rounded to the next 
32-word boundary. 

Format 

CALL $EXTSK 

Input 

block size 

In Register 1: the size (number of bytes less than or equal to 512 10 ) of the memory storage 

block to be allocated 

Output 

extension size 

In Register 1: the actual extension size (requested size rounded to next 32-word boundary) 

Condition Code 

C bit = Clear if extension was successful 

C bit = Set if extension failed 

Description 

The $EXTSK routine is called by the Get Core Routine ($GTCOR) when there is insufficient 

space in the current free dynamic memory to satisfy a memory block allocation request. The 

$EXTSK routine rounds the requested extension size to the next 32-word boundary. If there is 

enough memory space available, $EXTSK extends the task region, returning the total amount 

of the extension, in Register 1, to the $GTCOR routine. It preserves all other registers of the 

caller. If it cannot extend the task region, the $EXTSK routine sets the C bit in the Condition 

Code and returns to the $GTCOR routine. 

While you can call the $EXTSK routine directly, the routine is also called by the Initialize 

Dynamic Memory Routine ($INIDM), described in Chapter 7. 

The interaction of the $EXTSK routine with the $GTCOR routine (in statistical module GTCOS) 

is shown in Figure 8-5. 
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Figure 8-5: General Block Diagram of the $EXTSK Routine 
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Example 

The following source statements call the $EXTSK routine to extend the amount of memory 
available to the task: 



T$KINC == 256. 

T$KMAX == 

P$TADDR:.WORD 

FRHD: .BLKW 2 



TASK INCREMENT 
MAXIMUM SIZE OF TASK 
NEXT FREE ADDRESS 
FREE MEMORY LISTHEAD 
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CALL $SAVRG 



10$: 





MOV 


Rl.-(SP) ; 




MOV 


#FRHD,RO ; 




CALL 


$RQCB ; 




BCC 


60$ ; 




MOV 


#P$TADDR,R3 : 




MOV 


(R3) ,R2 ; 




CMP 


R2,#T$KMAX ; 




BHIS 


17$ ; 




MOV 


#T$KINC,R1 ; 




CALL 


$EXTSK ; 




BCS 


ERR$ ; 




ADD 


Rl.FRHD 




ADD 


R1.(R3) ; 




BR 


47$ 


17$: 








MOV 


#-l,(R3) ; 


47$: 








MOV 


#FRHD,RO ; 




CALL 


$RLCB 




MOV 


(SP)+,R1 ; 




BR 


10$ 


60$: 








INC 


(SP) + 




RTS 


PC 



SAVE NONVOLATILE REGISTERS 

SAVE BYTE COUNT 

GET ADDRESS OF FREE CORE POOL 

REQUEST CORE BLOCK 

IF C BIT CLEAR, SPACE IS ALLOCATED 

GET POINTER TO NEXT FREE ADDRESS 

GET NEXT FREE ADDRESS 

IS TASK AT MAXIMUM ALLOWABLE SIZE? 

IF TASK HIGHER OR SAME, YES 

GET TASK INCREMENT (IN BYTES) 

EXTEND THE TASK 

IF C BIT SET, EXTENSION FAILED 

ADD INCREMENT TO POOL 

UPDATE TOP OF MEMORY 

RELEASE BLOCK TO POOL 

BLOCK FURTHER ATTEMPTS TO EXTEND TASK 

GET ADDRESS OF FREE CORE POOL 
RELEASE MEMORY 
RESTORE BYTE COUNT 
BEGIN AGAIN 

CLEAN STACK, LEAVE C BITS INTACT 



8.3.5 Write Page Routine ($WRPAG) 

The $WRPAG routine transfers a memory page to the disk work file. 
Format 

CALL $WRPAG 

Input 

page address 

In Register 2: the dynamic memory address of the page to be transferred to disk 

error code 

In the task: the definitions for the following global symbols: 

E$R73 
S$V2 

Output 

Condition Code 

C bit = Clear if transfer succeeded 

C bit = Set if transfer failed 

error response 

If transfer is not successful, $WRPAG produces the following output: 
In Register 1: sets the error/severity codes E$R73 and S$V2 
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The SWRPAG routine then calls the user $ERMSG routine. 

Description 

The $WRPAG routine is called by the Get Core Routine ($GTCOR) to transfer to your disk 
work file a resident memory page that has been written into. 

The $WRPAG routine calls the $SAWR routine to save and subsequently restore Registers 
through 2 of the caller. The routine then performs the following actions: 

• Sets up the disk work file address of the page to be transferred 

• Initiates the page-writing operation 

• Checks the status of the write operation 

• Indicates a successful transfer (clears the C bit in the Condition Code) and returns control to 
the $SAWR routine, or calls your $ERMSG routine if a fatal work file I/O error prevented 
the page transfer 

The interaction of the $WRPAG routine with the $GTCOR routine is shown in Figure 8-6 (see 
next page). 
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Figure 8-6: General Block Diagram of the $WRPAG Routine 
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Example 

The following source statements call the $WRPAG routine to transfer a memory page from 
buffer P$GNXT to the disk work file: 
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E$R4 

E$R73 

E$R76 

S$V2 

P$GNXT: .WORD 

MOV 
MOV 

MOV 
CALL 



4 

73 

76 

302 



R4.R5 
P$GNXT,R4 

R4.R2 
$WRPAG 



INSUFFICIENT WORK FILE DYNAMIC MEMORY 

WORK FILE I/O ERROR 

WORK FILE EXCEEDED 

SEVERITY 2 

NEXT PAGE WORK FILE 

SAVE PREDECESSOR 
GET NEXT PAGE 

SET UP BUFFER FOR TRANSFER 

WRITE OUT PAGE INTO DISK WORK FILE 



8.4 Virtual Memory Allocation Routines 

The virtual memory allocation routines manage the allocation of disk and memory storage to 
enable page swapping from the free dynamic memory to your disk work file. The three virtual 
memory allocation routines are as follows: 

• The Allocate Virtual Memory Routine ($ALVRT), which allocates disk and memory page 
blocks, maintains page control and address tables, and interfaces with the executing task 
and the core allocation and page management routines. 

• The Allocate Small Virtual Block Routine ($ALSVB), which allocates small page blocks of 
disk and memory storage within large page blocks to enable efficient use of storage. The 
$ALSVB routine interfaces with the $ALVRT routine and page management routines to 
ensure address and status control of small pages in memory and disk storage. 

• The Request Virtual Core Block Routine ($RQVCB), which manages page-block allocation 
on your disk work file when it is called by the $ALVRT routine. 

8.4. 1 Allocate Virtual Memory Routine ($ALVRT) 

The $ALVRT routine determines whether a page block of virtual storage can be allocated on 
your disk work file. If so, the $ALVRT routine allocates an equal amount of memory storage, 
updates page control and address tables, and returns the disk and memory addresses of the 
allocated page blocks to the caller. If the $ALVRT routine cannot allocate the requested storage, 
the error and severity codes E$R76 and S$V2 are stored in Register 1 and the user's $ERMSG 
routine (see Section 8.1.1) is called. 

Format 

CALL SALVRT 

Input 
block size 

In Register 1: the number of bytes to be allocated 

Note 
The maximum size of a page block is 512 ]0 bytes. 
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Output 

memory address 

In Register 0: the memory address of the allocated page block 
In Register 1: the virtual address of the allocated page block 

Description 

The $ALVRT routine calls the Request Virtual Core Block Routine ($RQVCB) to determine 
whether the requested storage can be allocated on the disk work file. If not, a fatal error is 
signalled and the $ALVRT routine calls your $ERMSG routine. 

If it can allocate the disk storage, the $RQVCB routine returns the disk page block address to 

the $ALVRT routine, which determines whether a page block of space is available in memory. 

If not, the Allocate Block Routine ($ALBLK) is called to allocate a page block. The $ALVRT 

routine then calls the Convert Virtual to Real Address Routine ($CVRL) to convert the virtual 

address to a memory address. 

The $ALVRT routine calls the Write-Marked Page Routine ($WRMPG) to set the "written into" 

flag of the memory page. It also calls the $SAVRG routine to save and restore Registers 3 

through 5 of the calling routine. 

Although you can call the $ALVRT routine directly, it is also called automatically by the Allocate 

Small Virtual Block Routine ($ALSVB). 

The interaction of the $ALVRT routine with your task and other virtual memory management 

routines is shown in Figure 8-7. 
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Figure 8-7: General Block Diagram of the $ALVRT Routine 



Task 
SALSVB 



»c 



c 



SSAVRG 



c 



SWRMPG 



> 



Set memory 
address of page 
in RO; set disk 
address of page 
in Rl ; transfer to 
SSAVRG to 
restore R3 - R5 



Call SWRMPG 
to flag page as 
written into 



-»4 SALVRT ) 



Call SSAVRG 
To save 
R3 R5 



Call SROVCB 
to request disk 
storage block 




Save disk page 
address; see if 
core page block 
available 




Call SCVRLto 
convert virtual 
address to real 
address 



SCVRL J 



/ SSAVRG J 



-/ SRQVCB J 



Call user's 
SERMSG 
routine 



U SERMSG J 



Call SALBLK 
to allocate 
core page block 



-—( SALBLK J 



Update 

paging/address 

tables 



Virtual Memory Management Routines 8-25 



Example 

The following source statements call the $ALVRT routine to allocate a page block of virtual 
memory on a disk file. In this example, the statements save the contents of Registers and 2 
before calling $ALVRT: 

INSUFFICIENT WORK FILE DYNAMIC MEMORY 

WORK FILE I/O ERROR 

WORK FILE EXCEEDED 

SEVERITY 2 

TEMPORARY BUFFER FOR VIRTUAL MEMORY 

TEMPORARY BUFFER FOR VIRTUAL MEMORY 

LENGTH OF VIRTUAL ELEMENT 

SAVE POINTER IN INPUT BUFFER 
SAVE NUMBER OF BYTES IN BUFFER 
LENGTH OF VIRTUAL ELEMENT TO REGISTER 1 
ALLOCATE VIRTUAL BLOCK 



E$R4 


== 


4 


E$R73 


== 


73 


E$R76 


== 


76 


S$V2 


== 


302 


TEMPI: 


.WORD 





TEMP2 : 


.WORD 





A.LEN: 


.BLKW 


1 




MOV 


RO, TEMPI 




MOV 


R2.TEMP2 




MOV 


A.LEN.R1 




CALL 


$ALVRT 



8.4.2 Allocate Small Virtual Block Routine ($ALSVB) 

The $ALSVB routine allocates small page blocks within large page blocks of disk and memory 
storage. Thus, the routine accommodates variable user allocation size requirements and 
minimizes wasted storage space. 

The $ALSVB routine initially allocates a large page block, then performs suballocation of 
requested small blocks within the large block. When the space within a large block is exhausted, 
a new large block is allocated by the $ALSVB routine. 

Format 

CALL $ALSVB 

Input 

memory block 

In the source program: a large memory block defined as follows: 

N$DLGH == 512. 

Note 

Normally, 512 is the size of a large memory block. In any case, it must be 
less than or equal to 512 10 . 

page block size 

In Register 1: the size of the page block to be allocated, where: 

Rl = Zero (0) to force the allocation of a large virtual page block on the first call to 
$ALSVB 

Rl = A value less than or equal to 512 10 specifying the size, in bytes, of the small page 
to be allocated 
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Output 

dynamic memory address 

In Register 0: the dynamic memory address of the allocated page block 

virtual address 

In Register 1: the virtual address of the allocated block 

Description 

When a small page block is to be allocated within an existing large page block, the $ALSVB 
routine calls the Convert Virtual to Real Address Routine ($CVRL) to do the following: 

• Locate the allocated large page, if it is memory-resident (if it is not resident, read the page 
from disk to memory) 

• Convert the virtual page address to a memory page address 

• Transfer the large page block from disk into the large memory page block 

The $ALSVB routine calls the Write-Marked Page Routine ($WRMPG) to set the "written into" 
flag of the allocated memory page. 

When a large page block is to be allocated, the Allocate Virtual Memory Routine ($ALVRT) is 
called to do the following: 

• Allocate the disk and dynamic memory of the requested large page block 

• Convert the virtual address to a memory address 

• Transfer the large block, if necessary, from disk to dynamic memory 

• Set the "written into" flag of the allocated page block 

The $ALSVB routine destroys the contents of Register 2 and preserves the contents of Registers 
3 through 5. ~ 

The interaction of the $ALSVB routine with other virtual memory management routines is 
shown in Figure 8-8 (see next page). 
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Figure 8-8: General Block Diagram of the $ALSVB Routine 
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E$R4 


== 


4 


E$R73 


== 


73 


E$R76 


== 


76 


S$V2 


== 


302 


N$DLGH 


== 


512. 


PIGSIZ 


== 


24 




MOV 


#P$GSIZ.R5 




MOV 


R5.R1 




ASL 


Ri 




CALL 


$ALSVB 




MOV 


R1,(R4) + 



Example 

The following source statements call the $ALSVB routine to allocate a block of memory within 
a larger block: 

INSUFFICIENT WORK FILE DYNAMIC MEMORY 

WORK FILE I/O ERROR 

WORK FILE EXCEEDED 

SEVERITY 2 

LARGE BLOCK SIZE 

SIZE OF CURRENT PAGE 

GET PAGE SIZE 
COPY SIZE OF TABLE 
CONVERT TO BYTES 
ALLOCATE VIRTUAL MEMORY 
SAVE VIRTUAL ADDRESS 

8.4.3 Request Virtual Core Block Routine ($RQVCB) 

The $RQVCB routine manages page-block allocation on your disk work file. The $RQVCB 
routine is called by the Allocate Virtual Memory Routine ($ALVRT) when your task has 
requested allocation of a page block of a maximum of 512 10 bytes in length. 

The $RQVCB routine is not a user-called routine. 
Description 

The $RQVCB routine rounds the requested number of bytes up to the nearest word. If the 
rounded value crosses a disk block boundary, the $RQVCB routine allocates the page block 
beginning at the next disk block. 

If allocation is successful, the $RQVCB routine clears the C bit in the Condition Code and 
returns the disk address of the allocated page to the $ALVRT routine. 

If allocation is not successful, the $RQVCB routine sets the C bit in the Condition Code and 
returns control to the $ALVRT routine. The following conditions can prevent allocation: 

• There is no more disk storage space available. 

• A page block size greater than 512i bytes has been requested. 

The interaction of the $RQVCB routine with the $ALVRT routine is shown in Figure 8-9 (see 
next page). 
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Figure 8-9: General Block Diagram of the $RQVCB Routine 
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8.5 Page Management Routines 

The page management routines perform the processing required to control page swapping 
between dynamic memory and disk file storage. This processing includes address conversion; 
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page location; page transfer from disk to memory; and page status handling such as 
timestamping, flagging as "written into/ and locking and unlocking memory pages. 

The page management routines are as follows: 

• The Convert and Lock Page Routine ($CVLOK), which converts a virtual address to a 
dynamic memory address and locks the page in memory when called by your task 

• The Convert Virtual to Real Address Routine ($CVRL), which converts a virtual address to 
a dynamic memory address when called by one of the following: 

— The user task 

— The Allocate Virtual Memory Routine ($ALVRT) when a new disk page has been 
allocated 

— The Convert and Lock Page Routine ($CVLOK) when a page address is to be converted 
and the page is to be locked in memory 

• The Read Page Routine ($RDPAG), which is called by the $CVRL routine to transfer a page 
from your disk work file to dynamic memory 

• The Find Page Routine ($FNDPG), which determines whether a virtual page is resident in 
dynamic memory when called by one of the following: 

— The $CVRL routine 

— The Lock Page Routine ($LCKPG) 

— The Unlock Page Routine ($UNLPG) 

— The Write-Marked Page Routine ($WRMPG) 

• The Write-Marked Page Routine ($WRMPG), which sets the "written into" flag of memory 
pages when called by a user or by the $ALVRT and $ALSVB virtual memory allocation 
routines 

• The Lock Page Routine ($LCKPG), which is called by the $CVLOK routine and a user task 
to set a lock byte in a memory page to prevent its being swapped from memory to the disk 
file 

• The Unlock Page Routine ($UNLPG), which is called by a user task to clear a lock byte 
in a memory page to allow it to be swapped to disk storage to free memory space for 
reallocation 

8.5. 1 Convert and Lock Page Routine ($CVLOK) 

The $CVLOK routine performs the following functions: 

• Converts a virtual address to a memory address 

• Locks the page in memory 

Format 

CALL ICVLOK 
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Input 

virtual address 

In Register 1: the virtual address you want to convert 

Output 

converted memory address 
In Register 

virtual address 
In Register 1 

Condition Code 

C bit = Clear if the address was converted and the page locked 

C bit = Set if address conversion or page locking failed 

Description 

The $CVLOK routine calls the following routines: 

• The Convert Virtual to Real Address Routine ($CVRL) to convert the virtual address to a 
memory address 

• $CVRL to preserve the contents of Registers 3 through 5 

• The Lock Page Routine ($LCKPG) to lock the page in memory 

$CVLOK also preserves the contents of Register 2. 

The interaction of the $CVLOK routine with the calling task and other page management 
routines is shown in Figure 8-10. 
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Figure 8- 1 0: General Block Diagram of the $CVLOK Routine 
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Example 

The following source statements call the SCVLOK routine to convert a virtual address from 
the listhead to a dynamic memory address in TEMPI and then an error routine in case the 
conversion fails: 
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E$R4 


== 


4 


E$R73 


== 


73 


E$R76 


== 


76 


S$V2 


== 


302 


TEMPI: 


.WORD 





LISTHD: 


.BLKW 


1 




MOV 


LISTHD, Rl 




CALL 


$CVLOK 




BCS 


LCKERR 




MOV 


RO. TEMPI 


LCKERR: 


MOV 


#ERR55,R0 




BR 


ERROR 



INSUFFICIENT WORK FILE DYNAMIC MEMORY 

WORK FILE I/O ERROR 

WORK FILE EXCEEDED 

SEVERITY 2 

TEMPORARY STORAGE FOR VIRTUAL MEMORY 

LISTHEAD LOCATION 

MOVE VIRTUAL ADDRESS 

CONVERT. STORE REAL ADDRESS IN REGISTER 

ERROR 

SAVE IN TEMPORARY BUFFER 

GET ERROR MESSAGE 
GET ERROR ROUTINE 

8.5.2 Convert Virtual to Real Address Routine ($CVRL) 

The $CVRL routine converts a virtual address to a dynamic memory address. Virtual address 
units are words and dynamic memory addresses are bytes. 

Format 

CALL $CVRL 

Input 

virtual address 

In Register 1: the virtual address you want to convert 

Output 

memory address 

In Register 0: the converted memory address 

Description 

The $CVRL routine may be called directly in the task or indirectly by the following routines: 

• Allocate Virtual Memory Routine ($ALVRT) when a new disk page has been allocated 

• Convert and Lock Page Routine ($CVLOK) when the executing task has specified that a 
virtual address is to be converted to a memory address and the page is to be locked in 
memory 

The $CVRL routine calls the Find Page Routine ($FNDPG) to determine whether the specified 
page is resident in memory. If so, the virtual address is converted to a memory address, which 
is returned to the caller. If the page is not in memory, $CVRL calls the Allocate Block Routine 
($ALBLK) to allocate a memory page block. The $CVRL routine then calls the Read Page 
Routine ($RDPAG) to transfer the disk page into dynamic memory. The page address is then 
converted to a memory address. The memory address of the specified word in the page is 
stored in Register 0, and control is transferred to the $SAVRG routine, which restores Registers 
3 through 5 and returns to the caller. 

The $CVRL routine leaves Register 1 unchanged. It destroys the contents of Register 2. 

The interaction of the $CVRL routine with the caller and other virtual memory management 
routines is shown in Figure 8-11. 
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Figure 8-11: General Block Diagram of the $CVRL Routine 
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Example 

The following source statements call the $CVRL routine to convert a virtual address in Register 
1 to a dynamic memory address and store the result in Register 0: 



E$R4 


== 


4 


INSUFFICIENT WORK FILE DYNAMIC MEMORY 


E$R73 


== 


73 


WORK FILE I/O ERROR 


E$R76 


== 


76 


WORK FILE EXCEEDED 


S$V2 


== 


302 


SEVERITY 2 


P$GSIZ 


== 


24 


SIZE OF CURRENT PAGE 


P$GADR: 


.BLKW 


1 


ADDRESS OF CURRENT PAGE 
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20$: 



MOV 


#P$GADR,R1 


MOV 


Hl.RB 


TST 


Rl 


BNE 


20$ 


MOV 


#P$GSIZ.R1 


CALL 


$ALBLK 


MOV 


R5.R1 


CALL 


$CVRL 



GET PAGE ADDRESS 
SAVE VIRTUAL ADDRESS 
IS REQUEST ON BLOCK BOUNDARY? 
IF NO. BLOCK ALREADY EXISTS 
CREATE A PAGE BUFFER 
ALLOCATE STORAGE SPACE 
RESTORE VIRTUAL ADDRESS 
CONVERT TO REAL ADDRESS 



8.5.3 Read Page Routine ($RDPAG) 

The $RDPAG routine transfers a disk page from the work file to the dynamic memory. 
Format 

CALL $RDPAG 

input 

page address 

In Register 0: the disk address of the page you want to transfer 

Output 

Condition Code 

C bit = Clear if transfer succeeds 

C bit = Set if transfer fails 

Description 

The $RDPAG routine is called by the Convert Virtual to Real Address Routine ($CVRL) when 
a disk page is to be transferred to dynamic memory. The $RDPAG routine then does the 
following: 

• Sets up the address of the page to be transferred 

• Initiates the page-reading operation 

• Checks the status of the read operation 

• Calls the $SAWR routine to save and subsequently restore the caller's Registers 
through 2 

The interaction of the $RDPAG routine with the task and the $CVRL routine is shown in 
Figure 8-12. 
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Figure 8-12: General Block Diagram of the $RDPAG Routine 



\^ J ISCVRL 



( SRDPAG j */ SSAVVR j 



Initiate read 
operation 
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Example 

The following source statements allocate a page in buffer P$GSIZ and call the $RDPAG routine 
to read the virtual page address into core memory: 
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E$R4 


== 


4 


INSUFFICIENT WORK FILE DYNAMIC MEMORY 


E$R73 


== 


73 


WORK FILE I/O ERROR 


E$R76 


== 


76 


WORK FILE EXCEEDED 


S$V2 


== 


302 


SEVERITY 2 


P$GSIZ 


== 


24 


SIZE OF PAGE 


P$GBLK: 


.BLKW 


100. 


RELATIVE BLOCK NUMBER 


LISTHD: 


.BLKW 


1. 


LISTHEAD LOCATION 


PAGLS: 


.BLKW 


1. 


ADDRESS OF PAGE LIST 


$CVRT: 


SAVRG 




SAVE NONVOLATILE REGISTERS 




MOV 


R1.R5 


COPY VIRTUAL ADDRESS 




SWAB 


R5 


POSITION BLOCK NUMBER TO LOW BYTE 




CALL 


$FNDPG 


SEARCH FOR PAGE 




BCC 


10$ 


IF C BIT CLEAR, PAGE IN CORE. 




MOV 


#P$GSIZ.R1 


GET SIZE OF PAGE BUFFER 




CALL 


IALBLK 


ALLOCATE MEMORY 




MOV 


PAGLS ,R4 


GET ADDRESS OF PAGE LIST 




BEQ 


5$ 


IF EQ NONE 




CLR 


R2 


SET FOR MOVB WITH NO EXTEND 




BISB 


R5.R2 


GET RELATIVE BLOCK NUMBER 




ASL 


R2 


CONVERT TO WORD OFFSET 




ADD 


R2.R4 


COMPUTE LIST ADDRESS 




MOV 


R0,(R4) 


STORE ADDRESS OF PAGE 


5$: 










MOVB 


R5,P$GBLK(R0) 


SET RELATIVE BLOCK NUMBER 




CALL 


IRDPAG 


READ PAGE INTO CORE 



8.5.4 Find Page Routine ($FNDPG) 

The $FNDPG routine searches an internal page address list to determine whether a virtual page 
has already been transferred into an allocated memory page block. 

Format 

CALL $FNDPG 

Input 

virtual page address 

In Register 1: the address of the page being searched for 

Output 

block address 

In Register 0: the memory page block address where the page is resident 

Condition Code 

C bit = Clear if page is resident 

C bit = Set if page was not found 
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Description 

The $FNDPG routine is called by the following virtual memory management routines: 

• Convert Virtual to Real Address Routine ($CVRL) when a virtual address is to be converted 
to a memory address 

• Lock Page Routine ($LCKPG) when a memory page is to be locked in core memory 

• Unlock Page Routine ($UNLPG) when a locked memory page is to be unlocked 

• Write-Marked Page Routine (SWRMPG) when the "written into" flag is to be set in a memory 
page 

The $FNDPG routine determines whether the specified page is resident in the task's dynamic 
memory. If so, the page is timestamped, its page block address is set in Register 0, the C bit in 
the Condition Code is cleared, and control returns to the caller. If the page is not resident in 
memory, the $FNDPG routine sets the C bit in the Condition Code and returns control to the 
caller. $FNDPG does not change the contents of Register 1. 

The interaction of the $FNDPG routine with a user task and the page management routines is 
shown in Figure 8-13. 

Figure 8-13: General Block Diagram of the SFNDPG Routine 
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P$GADR: 


.WORD 





P$GSIZ 


== 


24 




CALL 


$SAVRG 




MOV 


P$GADR.R1 




CALL 


$FNDPG 




BCC 


10$ 




MOV 


#P$GSIZ.R1 




CALL 


$ALBLK 



Example 

The following source statements call the $FNDPG routine to verify that a page address, stored 
in buffer P$GADR, exists in core memory. The example then calls $ALBLK to allocate the page 
block: 

VIRTUAL PAGE ADDRESS 
SIZE OF PAGE 

SAVE NONVOLATILE REGISTERS 

GET PAGE ADDRESS 

SEARCH FOR PAGE 

IF CLEAR, PAGE IN CORE 

GET SIZE OF PAGE BUFFER 

ALLOCATE MEMORY 

10$: 

8.5.5 Write-Marked Page Routine ($WRMPG) 

The $WRMPG routine sets the "written into" flag of the specified page in dynamic memory. 
Format 

CALL $WRMPG 

Input 

virtual page address 

In Register 1: the address of the page for which the flag is being set 

Output 

Condition Code 

C bit = Clear if the page was write-marked successfully 

C bit = Set if the specified memory page was not resident in the task's free dynamic 
memory 

Description 

The $WRMPG routine is called by the following virtual memory management routines: 

• Allocate Virtual Memory Routine ($ALVRT) when a disk page has been allocated in dynamic 
memory 

• Allocate Small Virtual Block Routine ($ALSVB) when a small page block has been allocated 
within a large page block 

$WRMPG calls the Find Page Routine ($FNDPG) to determine whether the specified page is 
resident in the task's memory. If not, the C bit in the Condition Code is set and control is 
transferred to the $SAWR routine to restore Registers through 2 and return to the caller. If 
the page is resident in memory, its "written into" flag is set, the C bit in the Condition Code is 
cleared, and control is transferred to the $SAWR routine to restore Registers through 2 and 
return to the caller. 
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The interaction of the $WRMPG routine with the caller and virtual memory management 
routines is shown in Figure 8-14. 

Figure 8-14: General Block Diagram of the $WRMPG Routine 
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Example 

The following source statements call the $WRMPG routine to mark a page and then call an 
error routine in case $WRMPG is not successful: 

TEMPI: .WORD ; TEMPORARY STORAGE FOR VIRTUAL MEMORY 

FREECT: .BLKW 1 ; NUMBER OF AVAILABLE PAGE ENTRIES 
ER58: .ASCIZ <15>/ACNT— Work file - page mark / 
.EVEN 
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MOV 


TEMPI. Rl 


MOV 


R5, TEMPI 


MOV 


CR0.CR3 


INC 


FREECT 


CALL 


$WRMPG 


BCS 


WRMERR 


WRMERR: MOV 


#ER58,R0 


BR 


ERROR 



SET $WRMPG ARGUMENT 

MOVE PREV PAGE ADDRESS TO VIRTUAL MEMORY 

UPDATE PREV VIRTUAL ADDRESS PAGE POINTER 

INCREMENT NUMBER OF PAGES AVAILABLE 

MARK PAGE "WRITTEN INTO" 

ERROR 



GET ERROR MESSAGE 
GET ERROR ROUTINE 



8.5.6 Lock Page Routine ($LCKPG) 

The $LCKPG routine sets a lock byte in a memory-resident page to prevent its being swapped 
from dynamic memory to the disk work file. 

Format 

CALL SLCKPG 

Input 

virtual page address 

In Register 1: a virtual address in the page to be locked in dynamic memory 

Output 

Condition Code 

C bit = Clear if the page was locked in memory 

C bit = Set if the page was not found 

Description 

The SLCKPG routine may be called by a user task or by the Convert and Lock Page Routine 
(SCVLOK). 

$LCKPG calls the Find Page Routine ($FNDPG) to determine whether the memory page is 
resident. If so, the page lock byte is set, the C bit in the Condition Code is cleared, and control 
is transferred to the $SAWR routine to restore Registers through 2 and return to the caller. 

If the specified page is not in memory, the $LCKPG routine sets the C bit in the Condition 
Code and returns control, by means of the SSAWR routine, to the caller. 

The interaction of the SLCKPG routine with the task and page management routines is shown 
in Figure 8-15. 
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Figure 8-15: General Block Diagram of the $LCKPG Routine 
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Example 

The following source statements call the $LCKPG routine to lock a page in dynamic memory if 
the listhead contains more than one element: 

TEMPI: .WORD ; TEMPORARY STORAGE FOR VIRTUAL MEMORY 

LISTHD: .BLKW 1 ; LISTHEAD LOCATION 

ER55: .ASCIZ <15>/ACNT —Work file - page lock / 
.EVEN 
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MOV 


LISTHD.R1 


MOVE 1ST VIRTUAL ADDRESS 




CALL 


$CVLOK 


1ST PAGE REAL ADDRESS IN REGISTER 




6CS 


LCKERR 


ERROR 




TST 


(RO) 


ONLY 1 ELEMENT? 




BNE 


40$ 


NO. MORE THAN ONE 




CALL 


$UNLPG 


YES, ONLY ONE, UNLOCK IT 


40$: 


MOV 


TEMPI, Rl 


SET UP VIRTUAL ADDRESS FOR $LCKPG 




CALL 


$CVRL 


SAVE REAL ADDRESS OF NEXT PAGE IN REGISTER 




CALL 


ILCKPG 


LOCK 




BCS 


LCKERR 


ERROR 


LCKEBR: 


MOV 


#ERR55.R0 


GET ERROR MESSAGE 




BR 


ERROR 


ERROR ROUTINE 



8.5.7 Unlock Page Routine ($UNLPG) 

The $UNLPG routine clears a lock byte in a memory-resident page to allow the page to be 
swapped from dynamic memory to the disk work file. 

Format 

CALL $UNLPG 

input 

virtual page address 

In Register 1: the virtual address of the page you want to unlock 

Output 

Condition Code 

C bit = Clear if the page was unlocked 

C bit = Set if the page was not found 

Description 

$UNLPG calls the Find Page Routine ($FNDPG) to determine whether the memory page is 
resident. If so, the page lock byte and the C bit in the Condition Code are cleared and control 
is transferred to the $SAWR routine to restore Registers through 2 and return to the caller. 

If the specified page is not in memory, the C bit in the Condition Code is set and control is 
returned, by means of the $SAWR routine, to the caller. 

The interaction of the $UNLPG routine with the task is shown in Figure 8-16. 
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Figure 8-16: General Block Diagram of the $UNLPG Routine 
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Example 

The following source statements call the $UNLPG routine to allow pages to be swapped from 
real memory to virtual memory: 
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TEMPI: 
TEMP2: 
FREECT : 
LISTHD: 
ER56: 



10$: 



.WORD 

.WORD 

.BLKW 

.BLKW 

.ASCIZ 

.EVEN 

MOV 

MOV 

MOV 

CLR 

CALL 

BCS 

TST 

BNE 

CALL 

BCS 



TEMPORARY STORAGE FOR VIRTUAL MEMORY 
TEMPORARY STORAGE FOR VIRTUAL MEMORY 
NUMBER OF AVAILABLE PAGE ENTRIES 
LISTHEAD LOCATION 



<15>/ACNT —Work file - page unlock / 



#LISTHD,TEMP2 

LISTHD, Rl 

Rl, TEMPI 

FREECT 

CVLOK 

LCKERR 

(RO) 

20$ 

$UNLPG 

UNLERR 



GET FIRST REAL ADDRESS POINTER 

MOVE FIRST VIRTUAL ADDRESS 

SAVE IN SECOND VIRTUAL ADDRESS BUFFER 

CLEAR NUMBER OF SWAPS PER PASS 

PUT REAL ADDRESS IN REGISTER 

ERROR. PAGE LOCK FAILED 

LINK = 0, ONLY ONE ELEMENT? 

NO, MORE THAN ONE 

YES, ONLY ONE, UNLOCK IT 

ERROR 



20$: 
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Chapter 9 

Summary Procedures 



The procedures for using the system library routines are summarized in the tables in this 
chapter. These summaries are presented as quick reference guides for users who are familiar 
with the detailed procedures and requirements for using individual routines, as described in the 
preceding chapters of this manual. 

Table 9-1: Register Handling Routines Summary 



Routine Name/ 
Mnemonic 



Function 



Call Statement 



Save All Registers 
$SAVAL 

Save Registers 3 — 5 
$SAVRG 

Save Registers — 2 
$SAWR 

Save Registers 1 — 5 
.SAVR1 



Saves/restores RO— R5 CALL $SAVAL 



Saves/restores R3— R5 JSR R5,$SAVRG 



Saves/restores RO— R2 JSR R2,$SAWR 



Saves/restores Rl— R5 JSR R5,.SAVR1 



Table 9-2: Arithmetic Routines Summary 



Routine Name/ 
Mnemonic 



Integer Multiply 
$MUL 



Integer Divide 
$DIV 



RO = Multiplier 
Rl = Multiplicand 
CALL $MUL 

RO = Dividend 
Rl = Divisor 
CALL $DIV 



Input Arguments and 

Call Statement Output 



RO = Product (high-order part) 
Rl = Product (low-order part) 
R2 — R5 preserved 

RO = Quotient 
Rl = Remainder 
R2 — R5 preserved 
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Table 9-2 (Cont.): Arithmetic Routines Summary 



Routine Name/ 
Mnemonic 


Input Arguments and 
Call Statement 


Output 


Double-Precision 
$DMUL 


Multiply RO = Multiplier 

Multiplicand: 

R2 = High-order part 
R3 = Low-order part 

CALL $DMUL 


RO = Product (high-order part) 
Rl = Product (low-order part) 
R4 — R5 preserved 
R2— R3 destroyed 
C = Clear 


Double-Precision Divide RO = Unsigned divisor 

$DDIV Dividend: 

Rl = High-order part 
R2 = Low-order part 
CALL $DDIV 


RO = Remainder 
Rl = Quotient (high-order part) 
R2 = quotient (low-order part) 
R3 preserved 


NOTE: The arithmetic routines accept unsigned input and produce unsigned 


results. 


Table 9-3: Input Data Conversion Routines Summary 


Routine Name/ 
Mnemonic 


Input Arguments and 
Call Statement 


Output 


Decimal to 
Binary Double 
Word 
.DD2CT 


R3 = Output address 
R4 = Number input characters 
R5 = Input string address 
CALL .DD2CT 


Successful: 

Converted number at output 
address: 

Word 1 = High-order part 
Word 2 = Low order part 
C - Clear 
Unsuccessful: 

C = Set 
All registers preserved 


Octal to 
Binary Double 
Word 
.OD2CT 


R3 = Output address 
R4 = Number input characters 
R5 = Input string address 
CALL .OD2CT 


Successful: 

Converted number at output 
address: 

Word 1 = High-order part 
Word 2 = Low-order part 
C = Clear 
Unsuccessful: 

C = Set 
All registers preserved 


Decimal to 

Binary 

$CDTB 


RO = Address first input byte 
CALL $CDTB 


RO = Address first byte of next string 
Rl = Converted number 
R2 = Terminating character 
R3 — R5 preserved 


Octal to 

Binary 

$COTB 


RO = Address first input byte 
CALL $COTB 


RO = Address first byte of next string 
Rl = Converted number 
R2 = Terminating character 



R3 — R5 preserved 
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Table 9-3 (Cont.): Input Data Conversion Routines Summary 



Routine Name/ 
Mnemonic 



Input Arguments and 
Call Statement 



Output 



ASCII to 
Radix-50 
$CAT5 



ASCII with 
Blanks to 
Radix-50 
$CAT5B 



RO = Address first input 

character 
Rl = (period is terminating 

character) 
Rl = 1 (period is valid character) 
CALL $CAT5 



RO = Address first input 

character 
Rl = (period is terminating 

character) 
Rl = 1 (period is valid character) 
CALL $CAT5B 



Successful: 

RO = Address next input character 
Rl = Converted Radix-50 value 
R2 = Terminating character 
C = Clear 

Unsuccessful: 

R2 = Illegal character 
C = Set 

R3 — R5 preserved 

Successful: 

RO = Address next input character 
Rl = Converted Radix-50 value 
R2 = Terminating character 
C = Clear 

Unsuccessful: 

R2 = Illegal character 
C = Set 

R3 — R5 preserved 



Table 9-4: Output Data Conversion Routines Summary 



Routine Name/ 
Mnemonic 



Input Arguments and 
Call Statement 



Output 



Binary Date 
Conversion 
$CBDAT 



Convert Binary 
to Decimal 
Magnitude 
$CBDMG 



Convert Binary 
to Signed 
Decimal 
$CBDSG 



RO = Output address 

Rl = Binary date 

R2 = (zero suppress) 

R2 = Nonzero (no zero suppress) 

CALL $CBDAT 

RO = Output address 

Rl = Binary number 

R2 = (zero suppress) 

R2 = Nonzero (no zero suppress) 

CALL $CBDMG 

RO = Output address 

Rl = Binary number 

R2 = (zero suppress) 

R2 = Nonzero (no zero suppress) 

CALL $CBDSG 



Converted date at output address 
RO = Next available output address 
R3 — R5 preserved 
Rl— R2 destroyed 



Converted number at output ad- 
dress 

RO = Next available output address 
R3 — R5 preserved 
Rl— R2 destroyed 

Converted number at output ad- 
dress 

RO = Next available output address 
R3 — R5 preserved 
Rl— R2 destroyed 
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Table 9-4 (Cont.): Output Data Conversion Routines Summary 



Routine Name/ 
Mnemonic 



Input Arguments and 
Call Statement 



Output 



Convert Double- 
Precision 
Binary to 
Decimal 
$CDDMG 



Convert Binary 
to Octal 
Magnitude 
$CBOMG 



Convert Binary 
to Signed 
Octal 
SCBOSG 



Convert Binary 
Byte to Octal 
Magnitude 
$CBTMG 



General Purpose 
Binary to 
ASCII 
$CBTA 



RO = Output address 

Rl = Input address 

R2 = (zero suppress) 

R2 = Nonzero (no zero suppress) 

CALL$CDDMG 



RO = Output address 

Rl = Binary number 

R2 = (zero suppress) 

R2 = Nonzero (no zero suppress) 

CALL $CBOMG 

RO = Output address 

Rl = Binary number 

R2 = (zero suppress) 

R2 = Nonzero (no zero suppress) 

CALL $CBOSG 

RO = Output address 

Rl = Binary byte 

R2 = (zero suppress) 

R2 = Nonzero (no zero suppress) 

CALL $CBTMG 

RO = Output address 

Rl = Binary value 

R2 = Conversion parameters: 

Bits 0—7: = Radix (2 to 16 10 ) 
Bit 8: = = Unsigned value 

= 1 = Signed value 
Bit 9: = = Zero suppress 
= 1 = No zero 
suppress 
Bit 10: = 1, replace leading 
zeros with blanks 
= 0, do not replace 
leading zeros with 
blanks 
Bits 11—15: = Field width 
(value 1—32) 
CALL $CBTA 



Successful: 

Converted number at output 

address 
Unsuccessful: 

String of ASCII asterisks at 

output address 
RO = Next available output address 
R3 — R5 preserved 
Rl— R2 destroyed 

Converted number at output 

address 

RO = Next available output address 

R3 — R5 preserved 

Rl— R2 destroyed 

Converted number at output 

address 

RO = Next available output address 

R3 — R5 preserved 

Rl— R2 destroyed 

Converted byte at output address 
RO = Next available output address 
R3 — R5 preserved 
Rl— R2 destroyed 



Converted number at output 

address 

RO = Next available output address 

R3 — R5 preserved 

Rl— R2 destroyed 
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Table 9-4 (Cont.): Output Data Conversion Routines Summary 



Routine Name/ 


Input Arguments and 




Mnemonic 




Call Statement 


Output 


Radix-50 to 




RO = Output address 


Converted number at output 


ASCII 




Rl = Radix-50 word 


address 


$C5TA 




CALL $C5TA 


RO = Next available output address 
R3— R5 not used 
Rl— R2 destroyed 


Table 9-5: 


Output Formatting Routines Summary 


Routine Name/ 


Input Arguments and 




Mnemonic 




Call Statement 


Output 


Uppercase 




RO = Input address 


Converted text at output address 


Text 




Rl = Output address 


R3— R5 not used 


$CVTUC 




R2 = Number input bytes 


R2 destroyed 






(cannot be zero) 


RO — Rl left pointing to the character 






CALL $CVTUC 


following the string 


Date String 




RO = Output address 


Converted date string at output address 


Conversion 




Rl = Input address 


RO = Next available output address 


$DAT 




CALL $DAT 


Rl = Address of next input word 
R3 — R5 preserved 
R2 destroyed 


Time 




RO = Output address 


Converted time string at output 


Conversion 




Rl = Input address 


address 


$TIM 




R2 = Parameter count: 


RO = Next available output address 






= or 1, hour (HH) 


Rl = Address of next input word 






= 2, hour:minute 


R3 — R5 preserved 






(HH:MM) 


RO— Rl updated 






= 3, hour:minute:second 


R2 destroyed 






(HH:MM:SS) 








= 4 or 5, 








hour:minute:second. 








tenth of second 








(HH:MM:SS.S) 








CALL $TIM 
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Table 9-5 (Cont.): Output Formatting Routines Summary 



Routine Name/ 
Mnemonic 



Input Arguments and 
Call Statement 



Output 



Converted/formatted data in output 

block 

RO = Address of last zero byte in output 

block 
Rl = Number of bytes in output block 
R2 = Address of next argument in 

argument block 
R3 — R5 preserved 



Edit Message Define ASCIZ input string 

$EDMSG directives in the form: 

%1 

%nl 

%V1 

where n = Optional decimal 
repeat count; V specifies an 
optional value to be used 
as a repeat count; and 
1 = One of the following 
characters: 

A = ASCII string transfer 
B = Binary byte to octal conversion 
D = Binary to signed decimal conversion 
E = Extended ASCII string transfer 
F = Form control insertion 
I = ASCIZ address 

M = Binary to decimal magnitude conversion, zero suppression 
N = New line insertion 
O = Binary to signed octal conversion 

P = Binary to octal magnitude conversion, no zero suppression 
Q = Binary to octal magnitude conversion, zero suppression 
R = Radix-50 to ASCII conversion 
S = Space insertion 

T = Double-precision binary to decimal conversion 
U = Binary to double-precision decimal conversion, no zero suppression 
X = Filename conversion 
Y = Date conversion 
Z = Time conversion 
< = Define fixed-length byte field 
> = Locate field mark 



Set up argument and output block: 
RO = Output address 
Rl = Input string address 
R2 = Argument block address 

CALL $EDMSG 
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Table 9-6: Dynamic Memory Management Routines Summary 



Routine Name/ 
Mnemonic 



Input Arguments and 

Call Statement Output 



Initialize 
Dynamic 
Memory 
$INIDM 



Request Core 

Block 

$RQCB 



Release Core 

Block 

$RLCB 



Include FREEHD: .BLKW 2 

in data section 

RO = Free memory listhead 

address 
CALL $INIDM 

RO = Free memory listhead 

address 
Rl = Byte size of block 
CALL $RQCB 



RO = Free memory listhead 

address 
Rl = Byte size of block 
R2 = Block memory address 



RO = Task's first address 
Rl = Free pool first address 
R2 = Size memory pool 
R3 — R5 not used 

Successful: 

RO = Block memory address 

Rl = Actual size of block 

C = Clear 
Unsuccessful: 

C = Set 
R3 — R5 preserved 
R2 destroyed 

Released block 
R3 — R5 preserved 
RO unchanged 
Rl— R2 destroyed 



Table 9-7: Virtual Memory Management Routines Summary 



Routine Name/ 
Mnemonic 



Input Arguments and 
Call Statement 



Output 



Initialize 


Define $FRHD block with 


Virtual 


first address of free memory 


Memory 


Define 4 global symbols: 


$INIVM 


W$KLUN (work file LUN) 




W$KEXT (work file 




extension size) 




N$MPAG (fast page search 




page count) 




$WRKPT (address of FDB) 




Rl = Free memory highest 




address 




CALL $INIVM 


Allocate 


Rl = Byte size of requested 


Block 


block 


$ALBLK 


CALL $ALBLK 



Successful: 

R0 = 

C = Clear 
Unsuccessful: 

RO = -2, file not opened 

RO = -1, file not marked 

C = Set 
R3 — R5 preserved 
Original contents RO — R2 destroyed 



Successful: 

RO = Block memory address 
Unsuccessful: 

User's $ERMSG routine is called 
R3 — R5 preserved 
RO— R2 destroyed 
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Table 9-7 (Cont.): Virtual Memory Management Routines Summary 



Routine Name/ 


Input Arguments and 




Mnemonic 


Call Statement 


Output 


Get Core 


Rl = Byte size of requested 


Successful: 


$GTCOR 


block 


RO = Block memory address 




CALL $GTCOR 


C = Clear 
Unsuccessful: 

C = Set 
R3 — R5 preserved 


Extend 


Rl = Byte size of requested 


Successful: 


Task 


block 


Rl = Actual extension size 


$EXTSK 


CALL $EXTSK 


C = Clear 
Unsuccessful: 

C = Set 
R2 — R5 preserved 


Write 


R2 = Memory address of page 


Successful: 


Page 


CALL $WRPAG 


C = Clear 


$WRPAG 




Unsuccessful: 

User's $ERMSG routine is called 
RO— R2 preserved 


Allocate 


Rl = Byte size of requested 


Successful: 


Virtual 


block 


RO = Allocated block memory address 


Memory 


CALL $ALVRT 


Rl = Allocated block disk address 


$ALVRT 




Unsuccessful: 



User's $ERMSG routine is called 
R3 — R5 preserved 
R2 destroyed 



Allocate 


Define N$DLGH - - 512 10 


RO = Block memory address 


Small 


Rl = Size of requested page 


Rl = Block virtual address 


Virtual 


block: 


R3 — R5 preserved 


Block 


= 0, for large block 


R2 destroyed 


$ALSVB 


allocation on first 
call to $ALSVB 
= A value less than or 
equal to 512 10 bytes 
for small page 
allocation 
CALL $ALSVB 




Convert and 


Rl = Virtual address 


Successful: 


Lock Page 


CALL $CVLOK 


RO = Memory address 


$CVLOK 




Rl = Virtual address 

C = Clear 
Unsuccessful: 

C = Set 
R2 — R5 preserved 



9-8 Summary Procedures 



Table 9-7 (Cont.): Virtual Memory Management Routines Summary 



Routine Name/ 
Mnemonic 


Input Arguments and 
Call Statement 


Output 


Convert Virtual 
to Real 
Address 
$CVRL 


Rl = Virtual address 
CALL $CVRL 


RO = Memory address 
R3 — R5 preserved 
Rl unchanged 
R2 destroyed 


Read Page 
$RDPAG 


RO = Page disk address 
CALL $RDPAG 


Successful: 

C = Clear 
Unsuccessful: 

User's $ERMSG routine is called 
RO— R2 preserved 


Find Page 
$FNDPG 


Rl = Page virtual address 
CALL $FNDPG 


Page found: 

RO = Block memory address 

C = Clear 
Page not found: 

C = Set 


Write-Marked 

Page 

$WRMPG 


Rl = Virtual address in page 
CALL $WRMPG 


C = Clear, page write-marked 
C = Set, page not found 
RO— R2 preserved 


Lock Page 
$LCKPG 


Rl = Virtual address in page 
CALL $LCKPG 


C = Clear, page locked 
C = Set, page not found 
RO— R2 preserved 


Unlock Page 
$UNLPG 


Rl = Virtual address in page 
CALL $UNLPG 


C = Clear, page unlocked 
C = Set, page not found 
RO— R2 preserved 
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Appendix A 



Universal Library Access 



On most RSX-11M-PLUS and Micro/RSX systems, you can create a universal library to store 
related groups of files. The LBR utility creates the universal library file with a file type ULB. By 
means of the LBR utility, you can subsequently insert files as modules in the library. 1 

To access a module of a universal library, a program can call the $ULA routine, which 
establishes the necessary conditions for access (read only). The $ULA routine first calls an 
initializing routine, $ULAIN, to validate that the library file is in the correct format and to 
obtain the needed information from the library header. $ULA then calls a second routine, 
$ULAFD, to read the module header, to position libary file pointers to the beginning of the 
module, and to establish the necessary FDB locations for the File Control System (FCS). 2 Once 
the necessary FDB locations are established, the program can access the module as if it were a 
separate file. That is, the program can perform GET$ operations in move mode for each record 
in the module. 

To call the $ULA routine, supply the following data: 

• In Register 0, the address of the universal library FDB. The library file must already be open 
for read access. 

• In Register 1, the address of a 42 8 -word buffer. The first two words of the buffer must 
contain the name (in Radix-50 format) of the module to be accessed. $ULA will put a copy 
of the module header from the library into the remaining lOOg (64io) bytes. Initialize the 
FDRC$A arguments urba and urbs (FDB offsets F.URBD and F.URBD+2) in the FDB for 
the library file. The $ULA routine saves the arguments, uses the space for storing module 
header information, and restores the values before returning control to the calling program. 

The $ULA routine produces the following data: 

• Register is unchanged. 

• Register 1 is unchanged. The $ULA routine fills in the 40-word buffer with a copy of the 
header for the module accessed. 



See the description of the LBR utility in the RSX-UM-PLUS Utilities Manual, or see the description of the DCL command LIBRARY in the 
RSX-UM-PLUS Command language Manual or in the Micro/RSX User's Guide. 

See the RSX-UM-PLUS and Micro/RSX I/O Operations Reference Manual for information on FCS and the use of FDB locations. 
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• The first seven words of the library file FDB contain the first seven words of the FDB of the 
module's associated input file (as if it were a separate input file). 

• The offset F.EFBK+2 of the library file FDB contains the last block number of the module. 

• The offset F.FFBY of the library file FDB contains the number of the next available byte 
past the end of the module. 

• The offset F.ERR of the library file FDB has the standard interpretations except for the 
following special meanings: 

— The symbol IE.BHD means either "File not a universal library" or "Bad library header." 

— The symbol IE.NSF means "No such module." 

• The C bit is set to indicate an error. 

To use the $ULA routine properly, use the following coding sequence: 



OPENS RO ; OPEN UNIVERSAL LIB FILE 

; STORE FIRST SEVEN WORDS OF LIBRARY FDB 
CALL $ULA 

GET$ RO : ACCESS MODULE IN MOVE MODE ONLY 

; RESTORE FIRST SEVEN WORDS OF LIBRARY FDB 
CL0SE$ RO or invoke $ULA again 

Note that the program must open the library file for read-only access. (To change a module in 
the universal library, use the LBR utility.) The program must save the first seven words of the 
library file FDB before calling the $ULA routine for the first time. The $ULA routine modifies 
these words during processing, but their original values are necessary either to access another 
module or to ensure that the library file is closed properly. The program must restore the 
seven words after accessing a module and before accessing another module or before closing 
the library file. 
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Index 



$ALBLK (Allocate block), 8-10 
$ALSVB (Allocate small virtual block), 8-26 
$ALVRT (Allocate virtual memory), 8-23 
ASCII number conversion 

ASCII to Radix-50 ($CAT5), 4-8 

ASCII with blanks to Radix-50 ($CAT5B), 

4-9 
decimal to binary 
($CDTB), 4-4 

double-word (.DD2CT), 4-1 
octal to binary 

double-word (.OD2CT), 4-3 
octal to binary ($COTB), 4-6 



B 



Binary conversion 

binary byte to octal ($CBTMG), 5-10 
binary date to decimal ($CBDAT), 5-2 
binary to signed decimal ($CBDSG), 5-5 
binary to signed octal ($CBOSG), 5-9 
binary to unsigned decimal ($CBDMG), 

5-3 
binary to unsigned octal ($CBOMG), 5-8 
double-precision binary to decimal 

($CDDMG), 5-6 
general purpose binary to ASCII ($CBTA), 

5-12 



$C5TA (Radix-50 to ASCII), 5-13 
$CAT5 (ASCII to Radix-50), 4-8 
$CAT5B (ASCII with blanks to Radix-50), 

4-9 
$CBDAT (Binary date to decimal), 5-2 
$CBDMG (Binary to unsigned decimal), 5-3 
SCBDSG (Binary to signed decimal), 5-5 



$CBOMG (Binary to unsigned octal), 5-8 
$CBOSG (Binary to signed octal), 5-9 
$CBTA (General purpose binary to ASCII), 

5-12 
$CBTMG (Binary byte to octal), 5-10 
$CDDMG (Double-precision binary to 

decimal), 5-6 
$CDTB (Decimal to binary), 4-4 
Conversion 

See ASCII number conversion 

See Binary conversion 

See Date conversion 

See Decimal conversion 

See Octal conversion 

See Radix-50 conversion 

See Time conversion 
$COTB (Octal to binary), 4-6 
$CVLOK (Page lock), 8-31 
$CVRL (Virtual to real address), 8-34 
$CVTUC (Uppercase text), 6-1 

D 

$DAT (Date conversion) 

alternate format, 6-4 

standard format, 6-3 
Date conversion 

alternate format date ($DAT), 6-4 

standard format date ($DAT), 6-3 
Dates 

specifying, 6-5 
$DDIV (Double-precision divide), 3-4 
Decimal conversion 

decimal to binary 
($CDTB), 4-4 

double-word (.DD2CT), 4-1 
$DIV (Integer divide), 3-2 
Divide routine 

divide ($DIV), 3-2 
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Divide routine (cont'd.) 

double-precision divide ($DDIV), 3-4 
$DMUL (Double-precision multiply), 3-3 
Double-precision divide ($DDIV), 3-4 
Double-precision multiply ($DMUL), 3-3 
Double-precision routine, 3-3 



$EDMSG (Edit message), 6-8 
$EXTSK (Extend task), 8-18 



$FNDPG (Find page), 8-38 

G 

$GTCOR (Get core), 8-15 



$INIDM (Initialize memory), 7-2 
$INIVM (Initialize virtual memory), 8-5 
Integer routine 

divide ($DIV), 3-2 

multiply ($MUL), 3-1 



$LCKPG (Lock page), 8-42 
Library routine 

communicating between, 1-1 to 1-2 

placing, 1-2 

searching, 1-2 

storing, 1-2 

M 

Memory management, 7-1 

See also Virtual memory management 

core blocks release ($RLCB), 7-4 

core blocks request ($RQCB), 7-3 

initialize ($INIDM), 7-2 
Message formatting, 6-1 

carriage return/line feed insertion, 6-12 

date conversion ($DAT) 
alternate format, 6-4 
standard format, 6-3 

edit directive ($EDMSG), 6-8 

extended ASCII, 6-11 

field mark, 6-14 

filename string, 6-14 

form-feed insertion, 6-11 

general, 6-8 

space insertion, 6-13 



Message formatting (cont'd.) 

time conversion ($TIM), 6-6 

uppercase text ($CVTUC), 6-1 
$MUL (Integer multiply), 3-1 
Multiply routine 

double-precision multiply ($DMUL), 3-3 

multiply ($MUL), 3-1 

N 

Numeric to ASCII, 5-2 

See also ASCII number conversion 
binary byte to octal 

($CBTMG), 5-10 
binary date to decimal 

($CBDAT), 5-2 
binary to signed decimal 

($CBDSG), 5-5 
binary to signed octal 

($CBOSG), 5-9 
binary to unsigned decimal 

(SCBDMG), 5-3 
binary to unsigned octal 

($CBOMG), 5-8 
double-precision binary to decimal 

($CDDMG), 5-6 
general purpose binary to ASCII ($CBTA), 

5-12 
Radix-50 to ASCII ($C5TA), 5-13 

O 

Octal conversion 

octal to binary 

double-word(.OD2CT), 4-3 

octal to binary($COTB), 4-6 
.OD2CT (Octal to binary 

double-word), 4-3 



Paging 
memory 
See Virtual memory management 

R 

Radix-50 conversion 

ASCII to Radix-50 ($CAT5), 4-8 

ASCII with blanks to Radix-50 ($CAT5B), 
4-9 

Radix-50 to ASCII ($C5TA), 5-13 
$RDPAG (Read page), 8-36 
Register handling 

of control swapping function, 2-1 
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Register handling (cont'd.) 

save all Registers ($SAVAL), 2-2 
save Registers 0-2 ($SAWR), 2-5 
save Registers 1-5 (.SAVR1), 2-6 
save Registers 3-5 ($SAVRG), 2-4 
$RLCB (Release core block), 7-4 
$RQCB (Request core blocks), 7-3 
$RQVCB (Request virtual core block), 8-29 

s 

$SAVAL (Save all Registers), 2-2 
.SAVR1 (Save Registers 1-5), 2-6 
$SAVRG (Save Registers 3-5), 2-4 
$SAWR (Save Registers 0-2), 2-5 
Single-precision routine 
See Integer routine 

T 

$TIM (Time conversion), 6-6 
Time conversion 
time ($TIM), 6-6 

U 

$ULA (Universal library), A-l 
Universal library 

creating, A-l 
SUNLPG (Unlock page), 8-44 

y 

Virtual memory management, 8-1 

See also Memory management 

address conversion ($CVRL), 8-34 

allocate ($ALVRT), 8-23 

allocate small virtual block ($ALSVB), 
8-26 

core blocks request ($RQVCB), 8-29 

$CVRL routine, 8-34 

error-handling, 8-2 

find page ($FNDPG), 8-38 

initialize ($INIVM), 8-5 

lock page ($LCKPG), 8-42 

memory storage 

allocate block ($ALBLK), 8-10 
extend task ($EXTSK), 8-18 
get core ($GTCOR), 8-12, 8-15 

page lock ($CVLOK), 8-31 

read page ($RDPAG), 8-36 

task-building requirements, 8-4 

unlock page ($UNLPG), 8-44 

write-marked page ($WRMPG), 8-40 



Virtual memory management (cont'd.) 
write page ($WRPAG), 8-20 

W 

$'WRMPG (Write-marked page), 8-40 
$WRPAG (Write page), 8-20 
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READER'S 
COMMENTS 



Your comments and suggestions are welcome and will help us in our 
continuous effort to improve the quality and usefulness of our documentation 
and software. 

Remember, the system includes information that you read on your terminal: 
help files, error messages, prompts, and so on. Please let us know if you have 
comments about this information, too. 

Did you find this manual understandable, usable, and well organized? Please make suggestions for 
improvement. 



Did you find errors in this manual? If so, specify the error and the page number. 



What kind of user are you? 



Programmer 



Nonprogrammer 



Years of experience as a computer programmer/user: 



Name 

Organization 

Street 

City 



Date. 



_ State 

or Country 



.Zip Code. 
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